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Simple Network Management Protocol (SNMP) 
APIs 


The Simple Network Management Protocol (SNMP) APIs include the: 


e@ SNMP Subagent APIs 
e@ SNMP Manager APIs 


Before using the SNMP APIs, read the Simple Network Management Protocol (SNMP) Support book om 


It describes how to configure the iSeries to use SNMP and discusses SNMP agents, subagents, managers, 
and management information base (MIBs). The book also discusses "Using the SNMP Subagent DPI API." 


You can get more information about SNMP and Distributed Protocol Interface (DPI) from Requests for 
Comment (RFC) on the Internet. A file called ways_to_get_rfcs has details about obtaining RFCs. To 
receive these details send an E-MAIL message as follows: 


To: rfc-info@ISLEDU 
Subject: gettingrfcs 
help: ways_to_get_rfcs 


DPI is described in RFC 1592, "Simple Network Management Protocol Distributed Protocol Interface," 
Version 2.0. 
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Simple Network Management Protocol (SNMP) 
Subagent APIs 


The SNMP Subagent APIs are: 


connectSNMPQ (Establish connection with SNMP agent) establishes a logical connection between 
the SNMP subagent and the local (the same iSeries) SNMP agent. 


debugDPIQ (Set DPI packet trace) sets the level of the Distributed Protocol Interface (DPD packet 
trace. 


disconnectSNMPQ (End connection with SNMP agent) ends the logical connection between the 
SNMP subagent and the iSeries SNMP agent. 


DPI PACKET LENQO (Get length of DPI packet) returns the length (number of bytes) of a 
Distributed Protocol Interface (DPI) packet. 


fDPIparseQ) (Free storage from DPI packet parse) frees storage that was previously allocated by a 
call to pDPIpacket() to store the DPI packet. 


fDPIsetQ (Free storage from DPI set packet) frees storage that was previously allocated for 
snmp_dpi_set_packet structures. 

mkDPIAreYouThere() (Make a DPI Are YouThere packet) makes a DPI Are YouThere packet and 
returns a pointer to the packet. 

mkDPIclose() (Make a DPI close packet) makes a DPI close packet and returns a pointer to the 
packet. 

mkDPlopen() (Make a DPI open packet) makes a Distributed Protocol Interface (DPI) open packet 
and returns a pointer to the packet. 


mkDPlregister() (Make a DPI register packet) makes a Distributed Protocol Interface (DPI) register 
packet and returns a pointer to the packet. 


mkDPlIresponse() (Make a DPI response packet) makes a DPI response packet and returns a pointer 
to the packet. 


mkDPIset() (Make a DPI set packet) makes a DPI set structure and adds it to a chained list of set 
structures if previous calls have been made. 


mkDPItrapQ (Make a DPI trap packet) makes a DPI trap packet and returns a pointer to the packet. 


mkDPlunregister() (Make a DPI unregister packet) makes a DPI unregister packet and returns a 
pointer to the packet. 

pDPIpacket() (Parse a DPI packet) parses a serialized Distributed Protocol Interface (DPI) packet 
to make it available for processing by the subagent. 


receiveDPIpacket() (Receive a DPI packet from the SNMP agent) obtains a copy of a DPI packet 
sent by the SNMP agent to the subagent, and returns the DPI packet to the caller. 


sendDPIpacket() (Send a DPI packet to the SNMP agent) sends a copy of a Distributed Protocol 
Interface (DPI) packet to the SNMP agent (on the same system as the subagent). 


waitDPIpacket() (Wait for a DPI packet) waits for a message on the data queue with which the 
subagent has previously connected (see connectSNMP()--Establish Connection with SNMP Agent). 


Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 
Make sure QSYSINC is installed on your system before using any of the functions. All of the SNMP 
subagent APIs use header file qtossapi.h. You can see this source in source file H, member name 
QTOSSAPI, in the QSYSINC library. 


The Simple Network Management Protocol (SNMP) subagent APIs can be used to dynamically extend the 
management information base (MIB) that the system SNMP agent is aware of. The MIB is extended, 
without any change to the SNMP agent itself, while the iSeries is running. Dynamically added MIB 
subtrees (as defined and supported by a program known as a subagent) provide this capability. You may 
now extend the remote and automated system management capabilities of the iSeries within the SNMP 
framework. So, for example, you could define an SNMP MIB group for your RPG and SQL application, 
and then use SNMP protocol data units (PDUs), such as get and set, to determine status information or to 
make changes in control variables. 


The term Distributed Protocol Interface (DPI) packet is used throughout this information. The DPI is an 
extension to SNMP agents that permit users to dynamically add, delete, or replace management variables in 
the local MIB without requiring recompilation of the SNMP agent. 


The diagram below shows typical DPI API call sequences that are used to accomplish the SNMP subagent 
functions that are listed. 


(A) Subagent initiation 
(B) Subagent registration (loop for multiple subtrees) 


(C) Normal processing loop for a subagent, starting with a wait for a (get, getnext, set...) packet from 
the SNMP agent (other may be an unregister or close packet) 


(D) Acommon call sequence that might be consolidated 
(E) Subagent initiated trap 
(F) Subagent termination 


A loop around mkDPIset() represents building a packet with multiple varbinds. 


DPI API Call Sequences--Example 
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connectSNMP()--Establish Connection with 
SNMP Agent 


Syntax 


#include <qtossapi.h> 


int connect SNMP ( 
char *queue_name, 
char *lib_name, 
long int timeout ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The connectSNMP() function establishes a logical connection between the SNMP subagent and the local 
(the same iSeries server) SNMP agent. The data queue named by the queue_name parameter is used by the 
SNMP agent as the target data queue in a call to the Send Data Queue (QSNDDTAQ) API when it sends a 
message to the subagent. Only a single connection is allowed per data queue and library, hence a subagent 
may have only a single data queue. (Of course, a subagent may have multiple registrations. See 


mkDPlregisterQ--Make a DPI Register Packet.) 


Authorities 


So that the subagent can receive messages from the SNMP agent, the following conditions must be met: 


e The library and data queue whose names are passed as a parameter in the connectSNMP( call 
must exist prior to the call. 


e The SNMP agent job must have write access to the data queue. If you suspect a problem with the 
data queue, check the job log of the SNMP agent job (QTMSNMP in subsystem QS YSWRK) for 
TCP4041 messages with reason code 001. 


Parameters 


queue_name 


(Input) The name of the data queue (as a null-terminated string) on which the subagent wants to 
receive Distributed Protocol Interface (DPI) packets. The value must conform to OS/400 rules for 
data queue names (such as using uppercase letters and starting with a letter, $, #, @, and so forth). 


lib_name 


(Input) The name of the OS/400 library (as a null-terminated string) to which the data queue 
belongs. QTEMP is not an allowed value. The value must conform to OS/400 rules for library 
names (such as using uppercase letters and starting with a letter, $, #, @, and so forth). 


Note that the actual character representation of the specific library name must be used. Special 
values such as *LIBL and *CURLIB are not allowed. 


timeout 


(Input) The amount of time in seconds that the subagent is willing to wait for a connection. This 
field may contain the following values: 


0 Unlimited wait 


> 0 The number of seconds to wait (maximum is 2 147 483 647) 


Any other values result in an error return code. 


Return Value 


The return values are defined in the <qtossapi.h> file in the QS YSINC library. 


0 


-2 


-3 


4 


-8 


snmpsa_RC_ok 
The call was successful. 
snmpsa_RC_err 


An exception occurred. Check the subagent job log for the exception information, correct the 
condition, and resubmit the subagent job. (This return code is only used when a more specific 
return code is not available.) 


snmpsa_RC_noagent 
The SNMP agent is not available. 
snmpsa_RC_mismatch 


There is a code-level mismatch between the agent and the subagent. If this occurs, report the 
problem to the appropriate service organization. 


snmpsa_RC_timedout 

The specified timeout value was exceeded. 

snmpsa_RC_parmerr 

A parameter error occurred. This is more likely caused by errors in the value of a parameter (for 
example, a value was too large or too small) or by a pointer parameter that has a NULL value and 
should not. For char* parameters, it may also be caused if the length of the string exceeds some 
limit. 

snmpsa_RC_lengtherr 


During an attempt to communicate with the agent, a length exception occurred. 


-9 — snmpsa_RC_buffer 


An internal buffer was not obtained. See any messages in the job log and correct any errors that are 
indicated, then retry the operation. 


-10 snmpsa_RC_duplicate 


The agent already has a subagent with this queue and library name. The subagent may continue as 
usual with the mkDPIopen() and mkDPIregister() functions. If these fail, the subagent should use 
different library and queue names. 


-13 snmpsa_RC_alreadyconnected 
The subagent is already connected using the same data queue and library names passed on the call. 


If the SNMP agent still does not forward requests to the subagent properly, use the 
disconnectSNMP() function, then the connectSNMP() function. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 


Protocol (SNMP) Support e book. 


Usage Notes 


The connectSNMP() function establishes a logical connection with the SNMP agent that is running on the 
same system as the subagent. This is normally the first subagent API that a subagent calls. 


This API, like all the subagent APIs, checks to ensure that the pointers passed are generally valid for user 
data, for example, user domain. Such audits occur for all pointer parameters and for all pointers that appear 
in all C structures that are passed as parameters. If one of these checks fail, a CPF9872 exception is 


generated. This can occur from all the subagent APIs except debugDPI(), DPILPACKET_LENO, and 
mkDPIAreYouThere(). 


Related Information 
e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e disconnectSNMP(--End Connection with SNMP Agent 


e mkDPlregisterQ--Make a DPI Register Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
int or 


rc = connectSNMP( "QABCDEFG", "LIBABC", 0 ); 


Tf (re) { 
/* Handle exception. */ 


} 
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debugDPI()--Set DPI Packet Trace 


Syntax 


#include <qtossapi.h> 


void debugDPI( int level ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The debugDPI() function sets the level of the Distributed Protocol Interface (DPI) packet trace. The trace 
consists of a representation (printed to STDERR) of DPI packets as they are parsed (by the pDPIpacket() 
function) or made (by one of the mkDPIxxx() APIs). The trace is written to ILE C standard error output. 


Parameters 


level 


(Input) The level of tracing to perform. If this value is zero, tracing is turned off. If it has any other 
value, tracing is turned on at the specified level. The higher the value, the more detail. A higher 
level includes all lower levels of tracing. Possible values follow: 


O Turn off packet tracing 
I Display packet creation and parsing 


2 Level 1, plus display the hexadecimal dump of incoming and outgoing DPI packets. 


Usage Notes 


The debugDPI() function is used to turn the DPI packet trace on or off. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e mkDPlregister()--Make a DPI Register Packet 


e mkDPlresponse()--Make a DPI Response Packet 


e@ pDPlIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
debugDPI (2); 


Following are some examples of the DPI packet trace. A simple way to view STDERR is to run your 
program in batch in a submitted job. 


The following is an example of a trace, with the level parameter set to 1, of a register packet made by the 
subagent's call to mkDPIregister(). This is indicated in the trace by the letter c (for create) at the beginning 
of a trace line. Immediately following that is the parse of the response packet that the subagent got back 
from the SNMP agent. This is indicated in the trace by the letter p (for parse) at the beginning of a trace 
line. 


cDPIpacket: Major=2, Version=2, Release=0, Id=1, Type=SNMP_DPI_REGISTER 
cDPIreg: subtree=1.3.6.1.2.3.4.5.6., priority=0, timeout=4 
view_selection=No 
bulk_selection=No 
pDPIpacket: Major=2, Version=2, Release=0, Id=1, Type=SNMP_DPI_RESPONSE 
pDPIresp: ret_code=0 [0x0] (noError), ret_index=255 
pDPIset: subtree=1.3.6.1.2.3.4.5.6, instance=** NONE ** 
object=1.3.6.1.2.3.4.5.6 
value_type=NULL ['04'H], value_len=0 
value=** NULL ** 


Next is an example of a "get" packet that is received by a subagent. Immediately following that is the 
response packet that the subagent built (indicated by the letter c) by calling mkDPIresponse(). 


pDPIpacket: Major=2, Version=2, Release=0, Id=2, Type=SNMP_DPI_GET 
Community=** NONE ** 
pDPIget: subtree=1.3.6.1.2.3.4.5.6., instance=1.0 
object=1.3.6.1.2.3.4.5.6.1.0 
cDPIpacket: Major=2, Version=2, Release=0, Id=2, Type=SNMP_DPI_RESPONSE 
cDPIresp: ret_code=0 [0x0] (noError), ret_index=0 
cDPIset: subtree=1.3.6.1.2.3.4.5.6., instance=1.0 
object=1.3.6.1.2.3.4.5.6.1.0 
value_type=Integer32 ['81'H], value_len=4 
value=1 [0x00000001] 


Next is an example of the trace with the level parameter set to 2. This causes a hexadecimal dump of the 
DPI packet to be generated when pDPIpacket() is called, in addition to the trace level of 1. Next is the 
same packet as parsed by pDPIpacket(), and immediately following that is the response packet that the 
subagent built by calling mkDPIresponse(). 


Dump of 33 byte incoming DPI packet: 
00 1f 02 02 00 00 03 02 00 00 f1 4b £3 4b £6 4b 
fl 4b £2 4b £3 4b £4 4b £5 4b £6 4b O00 £5 4b £0 
00 
pDPIpacket: Major=2, Version=2, Release=0, Id=3, Type=SNMP_DPI_GETNEXT 
Community=** NONE ** 
pDPInext: subtree=1.3.6.1.2.3.4.5.6., instance=5.0 
object=1.3.6.1.2.3.4.5.6.5.0 
cDPIpacket: Major=2, Version=2, Release=0, Id=3, Type=SNMP_DPI_RESPONSE 
cDPIresp: ret_code=0 [0x0] (noError), ret_index=0 
cDPIset: subtree=1.3.6.1.2.3.4.5.6., instance=6.0 
object=1.3.6.1.2.3.4.5.6.6.0 
value_type=Counter32 ['86'H], value_len=4 
value=6 [0x00000006] 
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disconnectSNMP()--End Connection with SNMP 
Agent 


Syntax 


#include <qtossapi.h> 


int disconnect SNMP ( 
char *queue_name, 
char *lib_name, 
long int timeout ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The disconnectSNMP() function ends the logical connection between the SNMP subagent and the OS/400 
SNMP agent. 


Authorities 


So that the subagent can receive messages from the SNMP agent, the following conditions must be met: 


e The library and data queue whose names are passed as a parameter in the connectSNMP( call 
must exist prior to the call. 


e@ The data queue and library names passed as parameters in the disconnectSNMP() call must be the 
same as used in the previous, successful connectSNMP() call. 


Parameters 


queue_name 


(Input) The name of the data queue (as a null-terminated string) on which the subagent was 
receiving Distributed Protocol Interface (DPI) packets. This should be the same data queue name as 
previously used in a call to connectSNMP(). 


lib_name 


(Input) The name of the OS/400 library (as a null-terminated string) to which the data queue 
belongs. This should be the same library name as previously used in a call to connectSNMP(. 


timeout 


(Input) The amount of time in seconds that the subagent is willing to wait for a disconnection. This 


field may contain any of these values: 


0 Immediate disconnect, independent of whether or not the SNMP agent is available or has 
responded 


> 0 The number of seconds to wait (maximum is 2 147 483 647) 


Any other values result in an error return code. 


Return Value 


The indicated return values are defined in the <qtossapi.h> file. 


0 


-2 


-3 


4 


-9 


snmpsa_RC_ok 
The disconnectSNMP() function was successful. 
snmpsa_RC_err 


An exception occurred. Check the subagent job log for the exception information, correct the 
condition, and resubmit the subagent job. (This return code is only used when a more specific 
return code is not available.) 


snmpsa_RC_noagent 
The SNMP agent is not available. 
snmpsa_RC_mismatch 


There is a code-level mismatch between the agent and the subagent. If this occurs, report the 
problem to the appropriate service organization. 


snmpsa_RC_timedout 
The specified timeout value was exceeded. 
snmpsa_RC_parmerr 


A parameter error occurred. This is more likely caused by errors in the value of a parameter (for 
example, a value was too large or too small) or by a pointer parameter that has a NULL value and 
should not. For char* parameters, it may also be caused if the length of the string exceeds some 
limit. 


snmpsa_RC_lengtherr 


During an attempt to communicate with the agent, a length exception occurred. See any messages 
in the job log and correct any errors that are indicated, then retry the operation. 


snmpsa_RC_buffer 


An internal buffer was not obtained. See any messages in the job log and correct any errors that are 
indicated, then retry the operation. 


-14 snmpsa_RC_sync 


A synchronization problem occurred between the agent and subagent. If this occurs, report the 
problem to the appropriate service organization. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol (SNMP) Support e book. 


Usage Notes 


The disconnectSNMP() function ends the logical connection between the SNMP agent and a subagent. 
This is normally the last subagent API that a subagent calls. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e connectSNMPO--Establish Connection with SNMP Agent 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
int EC, 


re = disconnectSNMP( "QABCDEFG", "LIBABC", 0 ); 
if (re) { 
/* Handle exception. */ 


—— 
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DPI_PACKET_LEN()--Get Length of DPI Packet 


Syntax 


#include <qtossapi.h> 


int DPI_PACKET_LEN( unsigned char *packet_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The DPI_PACKET_LENQ( macro returns the length (number of bytes) of a Distributed Protocol Interface 
(DPI) packet. 


Parameters 


packet_p 
(Input) A pointer to a (serialized) DPI packet. 


Return Value 


value An integer value that represents the total DPI packet length. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 


Protocol (SNMP) Support e book. 


Usage Notes 


The DPI_PACKET_LEN() macro generates a C expression that returns an integer that represents the total 
length of a DPI packet. It uses the first 2 bytes (in network byte order) of the packet to calculate the length. 
The length returned includes these first 2 bytes. 


Example 


#include <qtossapi.h> 
unsigned char *pack_p; 
int length; 


pack_p = mkDPIclose(SNMP_CLOSE_goingDown) ; 
if (pack_p) { 


length = DPI_PACKET_LEN (pack_p) ; 
/* Send packet to agent or subagent. */ 
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fDPlparse()--Free Storage from DPI Packet 
Parse 


Syntax 


#include <qtossapi.h> 


void fDPIparse( snmp_dpi_hdr *hdr_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The fDPIparse() function frees storage that was previously allocated by a call to pDPIpacket() to store the 
DPI packet. 


Parameters 


hdr_p 


(Input) A pointer to an snmp_dpi_hdr structure. 


Usage Notes 


The fDPIparse() function frees dynamic storage that was previously created by a call to pDPIpacket(). 
After calling fDPIparse(), no further references should be made to hdr_p, which pointed to the 
snmp_dpi_hdr structure. 


A complete or partial DPI snmp_dpi_hdr structure is also implicitly freed by a call to a DPI function that 
serializes an snmp_dpi_hdr structure into a DPI packet. The section that describes each function tells you if 
this is the case. An example of such a function is mkDPIresponse(). 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e mkDPlresponse()--Make a DPI Response Packet 


e pDPIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 

snmp_dpi_hdr *hdr_p; 

unsigned char *pack_p; /* Assume pack_p points to 
/* incoming DPI packet. 

hdr_p = pDPIpacket (pack_p) ; 


/* Handle the packet, and when done, do the following. 
if (hdr_p) fDPIparse (hdr_p); 
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fDPlset()--Free Storage from DPI Set Packet 


Syntax 


#include <qtossapi.h> 


void fDPIset ( snmp_dpi_set_packet *packet_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The fDPIset() function frees storage that was previously allocated for snmp_dpi_set_packet structures. 


Parameters 


packet_p 


(Input) A pointer to the first snmp_dpi_set_packet structure in a chain of such structures. 


Usage Notes 


The fDPIset() function is typically used if you must free a chain of one or more snmp_dpi_set_packet 
structures. This may be the case if you are in the middle of preparing a chain of such structures for a DPI 
RESPONSE packet, but then run into an error before you can actually make the response. 


If you get to the point where you make a DPI response packet to which you pass the chain of 
snmp_dpi_set_packet structures, then the mkDPIresponse() function will free the chain of 
snmp_dpi_set_packet structures. Similarly, if you pass the chain of snmp_dpi_set_packet structures to 
mkDPItrap() to make a DPI trap request, the storage will be freed. 


Unnecessary free operations may result in an MCH6902 (type 2). If this occurs, remove the call to 
f{DPIset(). 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e mkDPlresponse()--Make a DPI Response Packet 


e@ mkDPlset()--Make a DPI Set Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 

unsigned char *pack_p; 
snmp_dpi_hdr *hdr_p; 
snmp_dpi_set_packet *set_p, 
long int numl = 


/* 


/* The subagent was waiting 
/* a message arrives... 


hdr_p = pDPIpacket (pack_p) ; 


/* analyze packet and assume all OK */ 
2 varBinds */ 


/* now prepare response; 


*first_p; 
0, num2 = 0; 

* / 
for work from the SNMP agent, and 


/* 
/* 
/* 


Assume pack_p 
points to the 
incoming packet. 


set_p = mkDPIset (snmp_dpi_NULL_p, /* Create first one 
"1 :3.6.1.2.3.4.5.0, "1.0", /* OID=1, instance=0 
SNMP_TYPE_Integer32, 
sizeof(numl), &numl); 
if (set_p) { /* If successful, then 
first_p = set_p; /* save pointer to first 
set_p = mkDPIset (set_p, /* chain. Next one 
"1.3.6.1.2.3.4.5.","1.1", /* OID=1, instance=1 
SNMP_TYPE_Integer32, 
sizeof(num2), &num2); 
if (set_p) { /*I£ successful, 2nd one 
pack_p = mkDPIresponse (hdr_p, /* makes response. 
SNMP_ERROR_noError, /* It will also free 
OL, first_p); /* the set_p tree. 
/* Send DPI response to agent. */ 
} else { /* If 2nd mkDPIset fails, 


fDPIset (first_p); 
} 
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mkDP!IAreYouThere()--Make a DPI AreYouThere 
Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPIAreYouThere( void ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIAreYouThere() function makes a DPI AreYouThere packet and returns a pointer to the packet. 


Parameters 


None. 


Return Value 


value 
The value returned is a pointer to the DPI packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first two bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LEN(O function can be used to calculate the total length of the DPI packet. 
NULL 


If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol (SNMP) Support e book. 


Usage Notes 


The mkDPIAreYouThere() function creates a serialized DPI ARE_YOU_THERE packet that can then be 
sent to the DPI peer (normally the agent). 


If your connection to the agent is still intact, the agent will send a DPI RESPONSE with 
SNMP_ERROR_ DPI noError in the error code field and zero in the error index field. The RESPONSE will 


have no varbind data. If your connection is not intact, the agent may send a response with an error 
indication, or may not send a response at all. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(O--Get Length of DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 


pack_p = mkDPIAreYouThere(); 
if (pack_p) { 

/* Send the packet to the agent. */ 
} 


/* Wait for response with waitDPIpacket(). * / 
/* Normally the response should come back fairly quickly, */ 
/* but it depends on the load of the agent. aA 
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mkDPIclose()--Make a DPI Close Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPIclose( char reason_code )j; 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIclose() function makes a DPI close packet and returns a pointer to the packet. 


Parameters 


reason_code 


(Input) The reason for the close. See the <qtossapi.h> file in the QSYSINC library for the list of 
defined reason codes. 


Return Value 


value The value returned is a pointer to the DPI packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LEN(O function can be used to calculate the total length of the DPI packet. 


NULL If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol (SNMP) Support book. 


Usage Notes 


The mkDPIclose() function creates a serialized DPI CLOSE packet that can then be sent to the DPI peer. 
As a result of sending the packet, the DPI connection will be closed. 


Sending a DPI CLOSE packet to the agent implies an automatic DPI UNREGISTER for all registered 
subtrees on the connection being closed. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(Q--Get Length of DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 


pack_p = mkDPIclose(SNMP_CLOSE_goingDown) ; 
if (pack_p) { 


/* Send the packet to the agent. */ 
} 
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mkDPlopen()--Make a DPI Open Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPLIopen ( 
char *oid_p, 
char *description_p, 
unsigned long timeout, 
unsigned long max_varBinds, 
char character_set, 
unsigned long password_len, 
unsigned char *password_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIopen() function makes a Distributed Protocol Interface (DPI) open packet and returns a pointer 
to the packet. 


Parameters 


oid_p 


(Input) A pointer to a NULL-terminated character string that represents the OBJECT IDENTIFIER, 
which uniquely identifies the subagent. 


description_p 


(Input) A pointer to a NULL-terminated character string, which is a descriptive name for the 
subagent. This can be any DisplayString, which basically is a byte string that contains only 
characters from the ASCII network virtual terminal (NVT) set. 


timeout 


(Input) The requested timeout for this subagent. An agent often has a limit for this value, and it will 
use that limit if this value is larger. A timeout of zero has a special meaning in the sense that the 
agent will then use its own default timeout value. The upper bound and default timeout values for 
DPI subagents are maintained by the SNMP agent in the subagent MIB. For details about the 


rat 
subagent MIB, see "SNMP Subagent MIB" in the Simple Network Management Protocol Ye 
book. 


max_varBinds 


(Input) The maximum number of varbinds per DPI packet that the subagent is prepared to handle. 
The agent tries to combine up to this number of varbinds (belonging to the same subtree) in a single 


DPI packet. If zero is specified, there is no explicit upper bound on the number of varbinds. In all 
cases, the actual number of varbinds is constrained by buffer sizes. 


character_set 


(Input) The character set that you want to use for string-based data fields in the DPI packets and 
structures. In general, the SNMP agent communicates to all SNMP managers in NVT ASCII and 
stores information in its own MIBs in ASCII. However, the agent will do some translations. 
Currently, only DPI_LNATIVE_CSET is supported. For the iSeries server, this is EBCDIC (coded 
character set identifier (CCSID) 500). 


The specifics are as follows: 


o On SET, COMMIT and UNDO requests from the agent, if the OID Structure of 
Management Information (SMI) type is SNMP_TYPE_OCTET_STRING and the textual 
convention is DisplayString, the agent will translate from ASCII to EBCDIC. The 
<qtossapi.h> file contains the C-language defines for these SMI types. 


Note: A subagent implementation with DisplayString OIDs that have read/write access 
should check the value_type in the snmp_dpi_set_packet (see the <qtossapi.h> file). If the 
value_type is not equal to the SNMP_TYPE_DisplayString in the set request, then the 
agent will not have converted from ASCII to EBCDIC. In this case, the subagent should 
perform the translation. 


o. If the textual convention is DisplayString during the processing of a GET or GETNEXT 
from a subagent, the agent will convert from EBCDIC to ASCIL. 


oOo When processing a DPI open packet, the agent will translate the description (see the 
description_p parameter) from EBCDIC to ASCII for storage in the subagent MIB. 


o Inthe SNMP MIB II system group, there are a number of DisplayString OIDs. These are 
all stored in ASCII. (The Internet standard RFC 1213, "Management Information Base for 
Network Management of TCP/IP-based internets: MIB-II", defines MIB II and the system 
group as well as other groups.) 


password_len 


(Input) The length (in bytes) of an optional password. For the iSeries server agent, subagents do not 
need to supply a password. If not, then a zero length may be specified. 


password_p 


(Input) A pointer to an byte string that represents the password for this subagent. This corresponds 
to an SNMP agent community name. A password may include any character value, including the 
NULL character. If the password_len is zero, then this can be a NULL pointer. 


Return Value 


value 


The value returned is a pointer to the DPI packet. 


If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LENQO function can be used to calculate the total length of the DPI packet. 


NULL If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol e book. 


Usage Notes 


The mkDPIopen() function creates a serialized DPI OPEN packet that can then be sent to the SNMP agent. 


The SNMP agent will send a DPI response packet back to the subagent with a code that can be used to 
determine if the open request was successful. This will be one of the SNMP_ERROR_DPI_* return codes 
found in <qtossapi.h>. Following receipt of this response packet, the subagent will need to call the 
pDPIpacket() to parse this DPI packet. The error_code should be checked. 


If the error_code is SNMP_ERROR_DPI_duplicateSubAgentldentifier, then another subagent with the 
same subagent OID has already sent an open DPI packet and the SA MIB OID saAllowDuplicateIDs is 2 
(No). Either choose a different OID for this subagent, change saAllowDuplicateIDs to 1 (Yes) or stop the 
other subagent that has the requested identifier. The fDPIparse() function would normally be called after 
that to free the parsed DPI response packet. For information about saAllowDuplicateIDs, see "SNMP 


Subagent MIB" in the Simple Network Management Protocol Ye book. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(Q--Get Length of DPI Packet 


e fDPIparse()--Free Storage from DPI Packet Parse 


e pDPIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 


pack_p = mkDPIopen("1.3.6.1.2.3.4.5", 
"Sample DPI sub-agent" 
OL,2L, DPI_NATIVE_CSET, 
0, (char *)0); 


if (pack_p) { 


/* Send packet to the agent. 


} 
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mkDPlregister()--Make a DPI Register Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPIregister ( 
unsigned short timeout, 
long int priority, 
char *group_p, 
char bulk_select); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIregister() function makes a Distributed Protocol Interface (DPI) register packet and returns a 
pointer to the packet. 


Parameters 


timeout 


(Input) The requested timeout in seconds. An agent often has a limit for this value, and it will use 
that limit if this value is larger. The value zero has special meaning in the sense that it tells the 
agent to use the timeout value that was specified in the DPI OPEN packet. 


priority 


(Input) The requested priority, relative to other DPI subagents. This field may contain any of these 
values: 


-1 The best available priority. 


0 A better priority than the highest priority currently registered. Use this value to obtain the 
SNMP DPI version 1 behavior. 


nnn Any other positive value. You will receive that priority if available; otherwise, the next 
best priority that is available. 


group_p 


(Input) A pointer to a NULL-terminated character string that represents the subtree to be registered. 
This group ID must have a trailing dot. 


bulk_select 


(Input) Whether you want the agent to pass GETBULK on to the subagent or to map them into 
multiple GETNEXT requests. The possible value follows: 


DPI_BULK_NO_ Do not pass any GETBULK requests, but instead map a GETBULK request 
into multiple GETNEXT requests. 


Return Value 
value The mkDPIregister() function was successful. The value returned is a pointer to the DPI 
packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LEN function can be used to calculate the total length of the DPI packet. 
NULL The mkDPIregister() function was not successful. 


If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


“ 
Protocol - book. 


Usage Notes 


The mkDPlregister() function creates a serialized DPI REGISTER packet that can then be sent to the 
SNMP agent. 


The SNMP agent will send a DPI response packet back to the subagent with a code that can be used to 
determine if the register request was successful. This will be one of the SNMP_ERROR_DPI_* return 
codes found in <qtossapi.h>. Following receipt of this response packet, the subagent will need to call the 
pDPIpacket() to parse the incoming DPI packet and to check the response packet error_code. Then, 
f{DPIparse() would normally be called to free the parsed DPI packet. 


If the response from the SNMP agent is SNMP_ERROR_DPI_higherPriorityRegistered, then a DPI 
subagent has already registered the same subtree at a higher priority than requested in this call. If so, this 
subagent will be contained in the subagent Management Information Base (MIB), and using an appropriate 
SNMP management application, you can determine its priority. You may want to consider requesting a 
higher priority or even -1 (best available) for your subagent. 


If the response from the SNMP agent is SNMP_ERROR_DPI_alreadyRegistered, then the requested 
subtree registration was for a portion of the overall MIB that is supported by an SNMP agent directly or by 
other system-implemented programs. Generally, registration of any subtree root, which would have the 
effect of masking all or portions of these subtrees (if allowed to occur), is prohibited. 


Not all protected subtrees are currently supplied on the iSeries server, although most are. If a subtree is 
currently not supplied, then the first subagent that dynamically registers it will be allowed, and later 
subagents will be disallowed. Refer to the "OS/400 SNMP Agent Set Processing and Supported SNMP 


MIBs" in the Simple Network Management Protocol Ye book for information on the MIB groups 
currently supplied with OS/400. 


Following are the protected subtrees and the associated MIB name: 


1.3.6.1.2.11 System 

1.3.6.1.2.1.2 Interfaces 

1.3.6.1.2.1.3 Address translation 

1.3.6.1.2.1.4 Internet Protocol 

1.3.6.1.2.1.5 Internet Control Message Protocol 
1.3.6.1.2.1.6 Transmission Control Protocol (TCP) 
1,3.6.1.2.1.7 User Datagram Protocol (UDP) 


1.3.6.1.2.1.10.7 Ethernet 

1.3.6.1.2.1.10.9 Token ring 

1.3.6.1.2.1. 10.15 Fiber distributed data interface (FDDI) 
1.3.6.1.2.1,10.32 Frame relay 


1.3.6.1.2.1.11 SNMP 
1.3.6.1.2.1.25 Host 
1.3.6.1.3.6 Interface extensions 


1.3.6.1.4.1,.2.2.12 Subagent 


1.3.6.1.4.1,.2.2.1 Distributed Protocol Interface (DPI) (See the Internet standard RFC 1592, "Simple 
Network Management Protocol Distributed Protocol Interface", Version 1.0.) 


1.3.6.1.4.1.2.6.2.13 Advanced Peer-to-Peer Networking®) (APPN‘®)) 
1.3.6.1.4.1.2.6.4.5 | NetView/6000 subagent computer system group 
1.3.6.1.4.1.2.6.50 Client management 

1.3.6.1.4.1.23.2.5 Internetwork Packet Exchange (IPX) protocol 
1.3.6.1.4.1.23.2.19 Netware Link Services Protocol (NLSP) 


1.3.6.1.4.1.23.2.20 Router Information Protocol (RIP) and Service Advertising Protocol (SAP) 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI PACKET LEN(Q--Get Length of DPI Packet 


e fDPIparseQ--Free Storage from DPI Packet Parse 


e pDPIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 


pack_p = mkDPIregister(0,0L,"1.3.6.1.2.3.4.5.", 
DPI_BULK_NO); 
if (pack_p) { 
/* Send packet to agent and await response. */ 


} 
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mkDPlresponse()--Make a DPI Response 
Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPI response ( 
snmp_dpi_hdr *hdr_p, 
long int error_code, 
long int error_index, 
snmp_dpi_set_packet *packet_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIresponse() function makes a DPI response packet and returns a pointer to the packet. 


Parameters 


hdr_p 


(Input) A pointer to the snmp_dpi_hdr structure of the DPI request to which this DPI packet will be 
the response. The function uses this structure to copy the packet_id and the DPI version and release 
so that the DPI packet is correctly formatted as a response. 


error_code 


(Input) The error code from the <qtossapi.h> file. 


error_index 


(Input) The first varbind in error. Counting starts at 1 for the first varbind. This field should be zero 
if there is no error. 


packet_p 


(Input) A pointer to a chain of snmp_dpi_set_packet structures. This partial structure will be freed 
by the mkDPIresponse() function. Therefore, on return, you cannot refer to it anymore. Pass a 
NULL pointer if there are no varbinds to be returned. 


Return Value 


value The value returned is a pointer to the DPI packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LEN(O function can be used to calculate the total length of the DPI packet. 


NULL If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination” in the book Simple Network 


a 
Management Protocol book. 


Usage Notes 


The mkDPIresponse() function is used by a subagent to prepare a DPI RESPONSE packet to a GET, 
GETNEXT, SET, COMMIT, or UNDO request. The resulting packet can be sent to the SNMP agent. 


Unnecessary free operations may result in an MCH6902 (type 2). If this occurs, remove the call to 
f{DPIset(). 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(Q--Get Length of DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 
snmp_dpi_hdr *hdr_p; 
snmp_dpi_set_packet *set_p; 
long int num; 


hdr_p = pDPIpacket (pack_p) ; /* Parse incoming packet. */ 
/* Assume it's in pack_p. */ 
if (hdr_p) { 
/* Analyze packet, assume GET, no error. */ 
set_p = mkDPIset (snmp_dpi_set_packet_NULL_p, 
WA 3260 2.34455 My MLO"; 


SNMP_TYPE_Integer32, 
sizeof (num), &num); 
if (set_p) { 

pack_p = mkDPIresponse (hdr_p, 
SNMP_ERROR_noError, OL, set_p); 

if (pack_p) { 

/* Send packet to subagent. */ 
} 
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mkDPlset()--Make a DPI Set Packet 


Syntax 


#include <qtossapi.h> 


snmp_dpi_set_packet *mkDPIset ( 
snmp_dpi_set_packet *packet_p, 
char *group_p, 
char *instance_p, 
int value_type, 
int value_len, 
void *value_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIset() function makes a DPI set structure and adds it to a chained list of set structures if previous 
calls have been made. 


Parameters 


packet_p 


(Input) A pointer to a chain of snmp_dpi_set_packet structures. Pass a NULL pointer if this is the 
first structure to be created. Typically, to handle multiple varbinds, this routine will be called 
repeatedly with this parameter having as its value the result returned from the previous call. Each 
new snmp_dpi_set_packet will be chained at the end. 


group_p 


(Input) A pointer to a NULL-terminated character string that represents the registered subtree that 
caused this GET request to be passed to this DPI subagent. The subtree must have a trailing dot. 


instance_p 


(Input) A pointer to a NULL-terminated character string that represents the rest (the piece 
following the subtree part) of the OBJECT IDENTIFIER of the variable instance being accessed. 
Use of the term instance_p here should not be confused with an OBJECT instance because this 
instance_p string may consist of a piece of the OBJECT IDENTIFIER plus the INSTANCE 
IDENTIFIER. 


value_type 
(Input) The type of the value. 


See the <qtossapi.h> file for a list of currently defined value types. 


value_len 


(Input) A signed integer that specifies the length (in bytes) of the value pointed to by the value_p 
parameter. The length may be zero if the value is of type SNMP_TYPE_NULL. 


value_p 


(Input) A pointer to the actual value. This parameter may contain a NULL pointer if the value is of 
(implicit or explicit) type SNMP_TYPE_NULL. 


Return Value 


value The value returned is a pointer to the DPI packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LENQO function can be used to calculate the total length of the DPI packet. 


NULL If unsuccessful, then a NULL pointer is returned. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol pe book. 


Usage Notes 


The mkDPIset() function is used at the subagent side to prepare a chain of one or more 
snmp_dpi_set_packet structures. This chain is then later used to create a DPI packet, using a call to 
mkDPIresponse() or mkDPItrapQ, which can then be sent to an SNMP agent. Each occurrence of an 
snmp_dpi_set_packet corresponds to a varbind in a protocol data unit (PDU). 


This function is unlike the other subagent APIs that have names beginning mkDPI, in that this function 
does not make a DPI packet that can be sent directly. Hence, it returns a pointer to an snmp_dpi_set_packet 
rather than a char * (as do the other mkDPI functions). 


Note that if the nth (n > 1) call to this function fails for some reason, the pointer to the chain of previously 
built snmp_dpi_set_packet structures will be lost unless the caller saves it. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(Q--Get Length of DPI Packet 


e fDPIset()--Free Storage from DPI Set Packet 


e mkDPlresponse()--Make a DPI Response Packet 


e@ mkDPltrapQ--Make a DPI Trap Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 


unsigned char *pack_p; 

snmp_dpi_hdr *hdr_p; 

snmp_dpi_set_packet *set_p; 

long int num; 

hdr_p = pDPIpacket (pack_p) /* Parse incoming packet. 


/* Assume it's in pack_p. 


if (hdr_p) { 
/* Analyze packet, assume GET, no error. */ 
set_p = mkDPIset (snmp_dpi_set_packet_NULL_p, 
"1 53566.0.2.53.445."%. "1.0", 
SNMP_TYPE_Integer32, 
sizeof(num), &num); 
if (set_p) { 
pack_p = mkDPIresponse (hdr_p, 
SNMP_ERROR_noError, 
OL, set_p); 
if (pack_p) 
/* Send packet to subagent. */ 


API introduced: V3R6 


Top | UNIX-Type APIs | APIs by category 


a7 
oy 


mkDPitrap()--Make a DPI Trap Packet 


Syntax 


#include <qtossapi.h> 


unsigned char *mkDPItrap ( 
long int generic, 
long int specific, 
snmp_dpi_set_packet *packet_p, 
char x*enterprise_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPItrap() function makes a DPI trap packet and returns a pointer to the packet. 


Parameters 


generic 


(Input) The generic trap type. The range of this value is 0 through 6, where 6 (enterpriseSpecific) is 
the type that is probably used most by DPI subagent programmers. The values 0 through 5 are 
well-defined standard SNMP traps. 


specific 


(Input) The (enterprise) specific trap type. This can be any value that is valid for the Management 
Information Base (MIB) subtrees that the subagent implements. 


packet_p 


(Input) A pointer to a chain of snmp_dpi_set_structures that represents the varbinds to be passed 
with the trap. This partial structure will be freed by the mkDPItrap() function; therefore, you cannot 
refer to it anymore on completion of the call. A NULL pointer means that there are no varbinds to 
be included in the trap. 


enterprise_p 


(Input) A pointer to a NULL-terminated character string that represents the enterprise ID (OBJECT 
IDENTIFIER) for which this trap is defined. A NULL pointer can be used. In this case, the 
subagent Identifier as passed in the DPI OPEN packet will be used when the agent receives the DPI 
TRAP packet. 


Note: This OID must not end in a period (.). 


Return Value 


value The value returned is a pointer to the DPI packet. 
If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of the 
buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LEN(O function can be used to calculate the total length of the DPI packet. 


NULL If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 


a 
Protocol - book. 


Usage Notes 


The mkDPItrap() function is used at the subagent side to prepare a DPI TRAP packet. The resulting packet 
can be sent to the SNMP agent. 


Unnecessary free operations may result in an MCH6902 (type 2). If this occurs, remove the call to 
fDPIset(). 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LEN(Q--Get Length of DPI Packet 


Example 


#include <qtossapi.h> 


unsigned char *pack_p; 
snmp_dpi_set_packet *set_p; 
long int num; 


set_p = mkDPIset (snmp_dpi_set_packet_NULL_p, 
WL Sie Orde 2 Shee Bee 7 LO 
SNMP_TYPE_Integer32, 
sizeof(num), &num); 
if (set_p) { 
pack_p = mkDPItrap(6,1,set_p, (char *)0); 
if (pack_p) | 
/* Send packet to subagent. */ 
} 
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mkDPlunregister()--Make a DPI Unregister 
Packet 


Syntax 


#include <qtossapi.h> 
unsigned char *mkDPIunregister ( 


char reason_code, 
char *group_p); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The mkDPIunregister() function makes a DPI unregister packet and returns a pointer to the packet. 


Parameters 


reason_code 


(Input) The reason for the unregister operation. See the <qtossapi.h> file for a list of defined 
reason codes. 


group_p 


(Input) A pointer to a NULL-terminated character string that represents the subtree to be 
unregistered. The subtree must have a trailing dot. 


Return Value 


pointer value The mkDPIunregister() function was successful. The value returned is a pointer to the 
DPI packet. 


If successful, then a pointer to a static DPI packet buffer is returned. The first 2 bytes of 
the buffer (in network byte order) contain the length of the remaining packet. The 
DPI_PACKET_LENQO function can be used to calculate the total length of the DPI 
packet. 


NULL The mkDPIunregister() function was not successful. 


If unsuccessful, then a NULL pointer is returned. 


Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a 
serialized DPI packet. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 


Protocol ee book. 


Usage Notes 


The mkDPlIunregister() function creates a serialized DPI UNREGISTER packet that can then be sent to 
the SNMP agent. Normally, the SNMP peer then sends a DPI RESPONSE packet back, which details if the 
unregister was successful or not. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e DPI_PACKET LENO--Get Length of DPI Packet 


Example 


#include <qtossapi.h> 
unsigned char *pack_p; 


pack_p = mkDPIunregister ( 
SNMP_UNREGISTER_goingDown, 
1.356.142. 354.5.%)7 
if (pack_p) { 
/* Send packet to agent or subagent and await response. */ 


} 
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pDPlipacket()--Parse a DPI Packet 


Syntax 


#include <qtossapi.h> 


snmp_dpi_hdr *pDPIpacket( unsigned char *packet_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The pDPIpacket() function parses a serialized Distributed Protocol Interface (DPI) packet to make it 
available for processing by the subagent. 


Parameters 


packet_p 
(Input) A pointer to a serialized (incoming) DPI packet. 


Return Value 
pointer value The pDPIpacket() function was successful. The value returned is a pointer to the DPI 
packet. 
If successful, a pointer to the snmp_dpi_hdr structure is returned. Storage for the 
structure has been dynamically allocated, and it is the caller's responsibility to free it 
when no longer needed. You can use the fDPIparse() function to free the structure. 


NULL The pDPIpacket() function was not successful. 


If unsuccessful, a NULL pointer is returned. 


For more information, see "SNMP Subagent Problem Determination” in the Simple Network Management 


Protocol (SNMP) Support ~ book. 


Usage Notes 


The pDPIpacket() function parses the buffer that is pointed to by the packet_p parameter. It ensures that 
the buffer contains a valid DPI packet and that the packet is for a DPI version and release that is supported 
by the DPI functions in use. 


Typical follow-on processing will examine the packet_type in the returned snmp_dpi_hdr, and take various 
actions to process the various types of DPI packets that may arrive. A subagent would normally expect to 
handle all the possible DPI packet types listed in <qtossapi.h>, except SNMPv2 types 
(SNMP_DPI_GETBULK and SNMP_DPI_TRAPV2), and types sent only to SNMP agents 
(SNMP_DPI_OPEN, SNMP_DPI_REGISTER, SNMP_DPI_TRAP, and SNMP_DPI_INFORM). Note that 
a close or unregister packet can be sent from an agent to the subagent. And if the subagent receives an 
are-you-there packet, it should build and send a response packet with the proper error_code. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e fDPlIparse()--Free Storage from DPI Packet Parse 


e@ pDPlIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 


unsigned char *pack_p; 
snmp_dpi_hdr *hdr_p; 
hdr_p = pDPIpacket (pack_p); /* Parse incoming packet. */ 


/* Assume it's in pack_p. */ 
if (hdr_p) { 
/* Analyze packet, and handle it. */ 
switch( hdr_p->packet_type) { 


} 
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receiveDPlpacket()--Receive a DPI Packet from 
the SNMP Agent 


Syntax 


#include <qtossapi.h> 


int receiveDPIpacket ( 
sa_datagq_msg *dataq_msg_p, 
void *dpi_msg_p, 
unsigned long int *length_p ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The receiveDPIpacket() function obtains a copy of a DPI packet sent by the SNMP agent to the subagent, 
and returns the DPI packet to the caller. 


Authorities 


Unlike the waitDPIpacket() function, this function does not actually refer to the subagent,s data queue. 


Parameters 


dataq_msg_p 


(Input) A pointer to the data queue message that was sent to the subagent to tell it that a DPI packet 
is pending. Note that the message must have already been received from the data queue by the 
subagent and placed in a buffer. This is a pointer to that message in the buffer. Use of this function 
assumes that the data queue messages are handled directly by the subagent,s own code. See 
waitDPIpacket() for an alternative. 


The sa_dataq_msg structure is defined in the <qtossapi.h> file. 


dpi_msg_p 
(I/O) A pointer to a buffer set up by the subagent that will contain the DPI serialized packet on 
successful return from this routine. 


length_p 


(Output) A pointer to an integer that will contain the length of the DPI packet contained in the 
subagent,s buffer on successful return. 


Return Value 


The return values are defined in the <qtossapi.h> file. 
0 snmpsa_RC_ok 
The call was successful. 
-] snmpsa_RC_err 


An exception occurred. Check the subagent job log for the exception information, correct the 
condition, and resubmit the subagent job. (This return code is only used when a more specific 
return code is not available.) 


-2. snmpsa_RC_noagent 
The SNMP agent is not available. 
-3  snmpsa_RC_mismatch 


A previous DPI packet was found. The subagent may want to process this packet or call 
receiveDPIpacket() again to get the next packet. See any messages in the job log and correct any 
errors that are indicated, then retry the operation. 


-5 — snmpsa_RC_nonagentmsg 
The data queue message is not from the SNMP agent. (There is no DPI packet pending.) 

-7 — snmpsa_RC_parmerr 
A parameter error occurred, probably a null pointer. 

-8 — snmpsa_RC_lengtherr 
A parameter was an incorrect length. 

-9 — snmpsa_RC_buffer 
Check the job log of the subagent for MCH3802. If found, the problem was likely due to agent 
workload, and the subagent can retry the request. If a different exception is found, see any 
messages in the job log, correct any errors that are indicated, and then retry the operation. 


-12 snmpsa_RC_connectfirst 


The subagent must connect to the SNMP agent before making this call. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 
Protocol e book. 


Usage Notes 


The receiveDPIpacket() function obtains a copy of a DPI packet sent to the subagent. The copy is placed 
in a buffer owned by the subagent. 


Use of this function by a subagent requires that the subagent programmer must wait for and receive the 
prompting message on the subagent,s data queue. An alternative is to use the waitDPIpacket() function, 
which handles the data queue for the subagent and also receives the DPI packet. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e@ waitDPlIpacket()--Wait for a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 


#define MAX _MSG_SIZE 4096 
char dpibuff [MAX_MSG_SIZE], 
datagqbuff[80]; 
int rc, len; 
/* Wait for message on data queue. When it arrives... */ 
QORCVDTAQ( ... ) 


/* Handle exceptions. */ 


re = receiveDPIpacket( &datagqbuff[0], 
&dpibuff[0], &len ); 
if (rc) { 
/* Handle exceptions. */ 


} 
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sendDPlpacket()--Send a DPI Packet to the 
SNMP Agent 


Syntax 


#include <qtossapi.h> 


int sendDPIpacket( void *dpimsg_p, int length ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The sendDPIpacket() function sends a copy of a Distributed Protocol Interface (DPI) packet to the SNMP 
agent (on the same iSeries server as the subagent). 


Parameters 


dpimsg_p 
(Input) A pointer to the serialized DPI packet. 


length 
(Input) The length in bytes of the DPI packet to be sent. 


Return Value 


The return values are defined in the <qtossapi.h> file. 
0 snmpsa_RC_ok 
The routine was successful. 
-] snmpsa_RC_err 


An exception occurred. Check the subagent job log for the exception information, correct the 
condition, and resubmit the subagent job. (This return code is only used when a more specific 
return code is not available.) 


-2.  snmpsa_RC_noagent 


The SNMP agent is not available. 


4 


-1] 


-12 


snmpsa_RC_timedout 

An internal time-out occurred. See the job log for further information about the exception. 
snmpsa_RC_parmerr 

A parameter error occurred, probably a null pointer. 

snmpsa_RC_lengtherr 


The length parameter may be incorrect, or the DPI packet to be sent is longer than the maximum 
length supported, or the length specified is not a positive number. See any messages in the job log 
and correct any errors that are indicated, then retry the operation. 


snmpsa_RC_buffer 


If the subagent was trying to send a response to an SNMP agent request (for example, using get 
packets), it cannot be sent. The subagent may continue. (The SNMP manager may retry the 
original request.) If the subagent was trying to send a subagent-initiated packet (for example, using 
open or register packets), then a dynamic buffer was unavailable, probably due to agent workload. 
The subagent may try to send the packet again. 


snmpsa_RC_canttrap 


A trap cannot be sent to the SNMP agent at this time, probably due to pending agent workload. The 
subagent may retry. 


snmpsa_RC_connectfirst 


The subagent must connect to the SNMP agent before making this call. 


For more information, see "SNMP Subagent Problem Determination" in the >Simple Network Management 
at 
Protocol om 


Usage Notes 


The sendDPIpacket() function sends a copy of a DPI packet that was sent to the SNMP agent. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 
unsigned char *pack_p; 


int rc; 


pack_p = mkDPIopen("1.3.6.1.2.3.4.5", 
"Sample DPI sub-agent" 
OL,2L, DPI_NATIVE_CSET, 
0, (char *)0); 

if (pack_p) { 


/* Send packet to the agent. */ 
re = sendDPIpacket( pack_p, DPI_PACKET_LEN(pack_p) ); 
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waitDPlpacket()--Wait for a DPI Packet 


Syntax 


#include <qtossapi.h> 


int waitDPIpacket ( 
long int timeout, 
void *dpimsgbuff_p, 
unsigned long int *length ); 


Service Program Name: QTOSSAPI 


Default Public Authority: *USE 


Threadsafe: No 


The waitDPIpacket() function waits for a message on the data queue with which the subagent has 
previously connected (see connectSNMP(--Establish Connection with SNMP Agent). When a Distributed 


Protocol Interface (DPI) packet arrives, this function receives the packet and copies it to a subagent buffer. 


Authorities 


So that the subagent can receive messages from the SNMP agent, the following conditions must be met: 


e The SNMP agent job must have write access to the data queue. If you suspect a problem with the 
data queue, check the job log of the SNMP agent job (QTMSNMP in subsystem QS YSWRK) for 
TCP4041 messages with reason code 001. 


Parameters 


timeout 


(Input) The number of seconds that the subagent is willing to wait for a message (a call to this 
function will block the subagent until a message is received or until this timeout is reached). 


Possible values have the indicated meaning; 
<0 Unlimited wait 
0 No wait. This causes an immediate return if a data queue message is not present. 


> 0 The number of seconds to wait (maximum is 99999), 


dpimsgbuff_p 
(I/O) A pointer to a buffer that is owned by the subagent. This will contain the serialized packet 


length 


from the SNMP agent when snmpsa_RC_ok is returned. The maximum length of a DPI packet is 
SNMP_DPI_BUFSIZE, defined in the <qtossapi.h> file. The buffer will contain the data queue 
message itself if that message is not from the SNMP agent, and waitDPIpacket() will return 
snmpsa_RC_nonagentmsg. 


(Output) When snmpsa_RC_ok is returned, the length (in bytes) of the DPI packet received. When 
snmpsa_RC_nonagentmsg is returned, the length of the data queue message. Otherwise, this value 
is 0. 


Return Value 


The return values are defined in the <qtossapi.h> file. 


0 


-2 


4 


-5 


-6 


-8 


snmpsa_RC_ok 

The routine was successful. 

snmpsa_RC_err 

An exception occurred. Check the subagent job log for the exception information, correct the 
condition, and resubmit the subagent job. (This return code is only used when a more specific 
return code is not available.) 

snmpsa_RC_noagent 

The SNMP agent is not available. 


snmpsa_RC_mismatch 


A previous DPI packet was found. The subagent may want to process this packet or call the 
receiveDPIpacket() function again to get the next packet. 


snmpsa_RC_timedout 

No message was received within the specified timeout. 
snmpsa_RC_nonagentmsg 

A data queue message arrived that is not from the SNMP agent. 
snmpsa_RC_dginvalid 


The subagent data queue or library is invalid. This refers to the data queue and library used in the 
connectSNMPQ(O call. 


snmpsa_RC_parmerr 
A parameter error occurred, probably a null pointer. 
snmpsa_RC_lengtherr 


A parameter was an incorrect length. 


-9 — snmpsa_RC_buffer 
Check the job log of the subagent for MCH3802. If found, the problem was likely due to agent 
workload, and the subagent can retry the request. If a different exception is found, see any 
messages in the job log, correct any errors that are indicated, and then retry the operation. 


-12 snmpsa_RC_connectfirst 


The subagent must connect to the SNMP agent before making this call. 


For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management 


a 
Protocol - book. 


Usage Notes 


The waitDPIpacket() function waits for a message on the data queue that the subagent specified on the 
connectSNMP( call. When a data queue message is received, the corresponding DPI packet is copied to 
the specified subagent buffer. 


If a data queue message arrives that is not from the SNMP agent, then it is returned in the buffer and the 
code snmpsa_RC_nonagentmsg is returned. 


Related Information 


e The <qtossapi.h> file (see Header Files for UNIX-Type Functions) 


e@ connectSNMP(--Establish Connection with SNMP Agent 


e@ pDPlIpacket()--Parse a DPI Packet 


Example 


See Code disclaimer information for information pertaining to code examples. 


#include <qtossapi.h> 


#define MAX _LEN 4096 
#define wait TIMEOUT 300 
unsigned char *pack_p, 

dpimsgbuff [MAX_LEN]; 
snmp_dpi_hdr *hdr_p; 
snmp_dpi_set_packet *set_p; 
long int num, length; 
for(;;) { 


re = waitDPIpacket ( waitTIMEOUT, 


&dpimsgbuff[0], length ); 
if (rce<0O) { 
/* Handle exceptions. */ 


} 


else { 


hdr_p = pDPIpacket (pack_p) ; /* Parse incoming packet. 
/* Assume it's in pack_p. 


if (hdr_p) { 
/* Analyze packet, assume GET, no error. */ 
set_p = mkDPIset (snmp_dpi_set_packet_NULL_p, 
Wee 6. ls 263.4255", “10%, 
SNMP_TYPE_Integer32, 
sizeof (num), &num); 
if (set_p) { 
pack_p = mkDPIresponse (hdr_p, 
SNMP_ERROR_noError, OL, set_p); 
if (pack_p) { 
/* Send packet to subagent. */ 


} /*end if*/ 
} /*end if*/ 
} /*end if*/ 
} /*end else*/ 
} /*end for*/ 
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ard 
a 


Simple Network Management Protocol (SNMP) 
Manager APIs 


The SNMP Manager APIs are: 
e snmpGet() (Retrieve MIB objects) is used to get one or more management information base (MIB) 
objects from an SNMP agent or subagent on a local or remote system. 
e snmpGetnextQ (Retrieve next MIB object) is used to get the value of one or more management 
information base (MIB) objects from an SNMP agent or subagent on a local or remote system. 


e snmpSet() (Set MIB objects) is used to set one or more management information base (MIB) 
objects in an SNMP agent or subagent on a local or remote system. 


Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 
Make sure QSYSINC is installed on your system before using any of the functions. All of the SNMP 
manager APIs use header file qtomeapi.h. You can see this source in source file H, member name 
QTOMEAPYI, in the QSYSINC library. 


For examples that use the SNMP manager APIs, see Using SNMP Manager APIs--Example. 


For information about trap support, see SNMP Trap Support. 


SNMP managing applications typically use APIs to establish communication with local or remote SNMP 
agents, and then call other APIs to retrieve or modify MIB objects managed by those agents. The OS/400 
SNMP manager APIs accomplish both of these tasks within the same API. Three manager APIs are 
provided to perform the SNMP GET, GETNEXT, and SET operations. In general, all three APIs are 
blocked. That is, when the application calls these APIs, the API constructs a proper SNMP message, 
delivers it to the proper SNMP agent, waits, decodes the response from the agent, and delivers the 
information to the application. No processing occurs in the application until the API delivers this 
information or times out. The communications mechanism between the manager APIs and agents uses 
sockets. Therefore, both systems need to support sockets. 


Application programmers who are writing network management applications can use the snmpGet(), 
snmpGetnext(), and snmpSet() SNMP APIs to retrieve and set management information base (MIB) data so 
that they can manage their systems and networks. Programmers should have a strong understanding of 
network management, SNMP, and some transport protocol such as Transmission Control Protocol/Internet 
Protocol (TCP/IP). 
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snmpGet()--Retrieve MIB Objects 


Syntax 


#include <qtomeapi.h> 


int snmpGet(snmppdu * pdu_ptr, 
char * host_ptr, 
unsigned long int time_out, 
char * comm_ptr, 
unsigned long int comm_len) ; 


Service Program Name: QTOMEAPI 


Default Public Authority: *USE 


Threadsafe: No 


An SNMP managing application uses the snmpGet() function to get one or more management information 
base (MIB) objects from an SNMP agent or subagent on a local or remote system. 


Parameters 


pdu_ptr 


(Input) A pointer to a structure of the protocol data unit (PDU) type as defined in the 
<qtomeapi.h> file. 


This structure contains the PDU type (GET in this instance), the error status, the error index, and 
the pointer to the varbind structure. 


The varbind structure (found in the qtomeapi.h file) consists of the following: 


struct _varBind{ 
struct _varBind * next; 
char *oid; /* Null Terminated */ 
unsigned char asn_type; 
int val_len; 
union { 
int * int_val; 
char * str_val; 
} val; 


}; 


The fields for this structure are described as follows: 


*next The pointer to the next varbind. This has to be NULL if it is the last varbind in the 
list. 


*oid The pointer to the OID being set or retrieved (depending on the operation). 


asn_type The ASN type of the OID. This field must be set by the user only for the snmpSet 
function. On the snmpGet or snmpGetnext function, it is returned by the API. 


val_len For the snmpSet function, the user must set this to reflect the exact amount of data to 
be written to the OID. On an snmpGet or snmpGetnext, the user must use this field to 
indicate how much space to allocate for the value being retrieved. If the value coming 
back is greater than the amount of space allocated, a return code of 1 is received. 


val A union of either a pointer to the string data or a pointer to the integer data. This 
space is allocated by the user. 


host_ptr 
(Input) A pointer to the character string that contains the Internet Protocol (IP) address. 
This parameter can be stored in dotted decimal notation, that is, 9.130.38.217, or in host address 
format, that is, oursystem.endicott.ibm.com. This parameter must contain printable characters only. 
time_out 
(Input) The time-out value. 
This parameter is the amount of time in seconds that the management application is willing to wait 
for the response PDU. The minimum value is 1, and the maximum is 100. 
comm_ptr 
(Input) A pointer to the character string that contains the community name. 
This parameter contains a variable-length field that contains printable and nonprintable values. 
Therefore, the user must supply the exact length of this value in another parameter. 


EBCDIC-to-ASCII translation will not be done, and it is the responsibility of the managing 
application to specify the community name in the correct notation for the SNMP agent system. 


comm_len 


(Input) The length of the community name. 


This parameter is the exact length of the community name. The minimum value is 1, and the 
maximum is 255. 


Authorities 


Service Program Authority 
*USE 


Return Value 


The following are the possible return codes posted by the snmpGet() function: 
0 API_RC_OK 


snmpGet() was successful. 


4 


-9 


-10 


-1] 


-12 


-13 


-18 


-103 


-104 


-108 


API_RC_OUT_OF_MEMORY 


There was not enough storage to complete this operation. 


API_RC_OUT_OF_BUFFERS 


There were not enough internal buffers to continue. 


API_RC_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. 


API_RC_SNMP_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. This return code is equivalent to the 
-6 return code. 


API_RC_SNMP_INVALID_OID 


The OID specified in the varbind list is not valid. This return code is equivalent to the -112 return 
code. 


API_RC_INVALID_VALUE 

The specified value in the varbind is not valid. 
API_RC_INVALID_VALUE_REP 

The specified value in the varbind is incorrectly represented. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to decode the incoming PDU. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to encode the PDU data structure. 
API_RC_TIMEOUT 

A response to this request was not received within the allotted time-out value. 
API_RC_INVALID_PDU_TYPE 

The PDU type was not recognized as one of the seven common PDU types. 
API_RC_INVALID_IP_ADDRESS 

The IP address that was specified is not valid. 
APTI_RC_INVALID_COMMUNITY_NAME 

_ LENGTH 

The community name length must be greater than 0 and less than 256. 
API_RC_INVALID_TIMEOUT_PARM 


The time-out value must be greater than 0 and less than or equal to 100. 


-110 


-112 


-113 


-114 


-115 


-201 


-202 


241 


242 


243 


API_RC_UNKNOWN_HOST 

The host name or IP address that is specified is not known on the network. 
API_RC_INVALID_OID 

The OID that is specified in the varbind list is not valid. 
API_RC_INVALID_PDU_POINTER 

The pointer value to the PDU structure must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the host address must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the community name must be non-NULL. 
API_RC_SOCKET_ERROR 

The APIs have detected a socket error and cannot continue. 
API_RC_NOT_OK 

The APIs have detected an unknown error and cannot continue. The val_len field of the varbind 


structure contains a value that is not valid. 


APTI_RC_VAL_LEN_LESS_THAN_RETURNED __ 
VAL_LEN 


The value being returned by the API is greater than the space allocated by the user. 
API_RC_DOMAIN_ERROR 
This is equivalent to an MCH6801 error--stating object domain error. 


API_RC_INVALID_POINTER 


This is equivalent to an MCH3601 error--referenced location in a space does not contain a 
pointer. 


API_RC_INVALID_PTR_TYPE 


This is equivalent to an MCH3602 error-pointer type not valid for requested operation. 


For more information, see "Problem Determination for SNMP Manager APIs" in the Simple Network 


a 
Management Protocol ~ book. 


Error Conditions 


Following are the possible error statuses returned in the error status field of the PDU structure. These values 
are returned by the SNMP agents. 


O APILSNMP_ERROR_noError 
The function was successful. 
I API_SNMP_ERROR_tooBig 
The agent could not fit the results of an operation into a single SNMP message. 
2 APISNMP_ERROR_ noSuchName 
The requested operation identified an unknown variable name. 
3 APILSNMP_ERROR _badValue 


The requested operation specified an incorrect syntax or value when the management application 
tried to modify a variable. 


5 API_SNMP_ERROR_ genErr 


A nonspecific error occurred while running this operation on the SNMP agent. 


Usage Notes 


The area where the data is returned is the responsibility of the user, not the API. To allocate storage, the 
user may use the AddVarbind routine (see AddVarbind Routine). To deallocate storage, the user may use 


the FreePdu routine (see FreePdu Routine). 


You must use the correct PDU type on AddVarbind. It must match the operation on which you call. For 
example, if you build a PDU wherein AddVarbind passes a PDU type of Set and then you call the snmpGet 
operation using the PDU that you just created with Set, you will receive an error on the snmpGet call. 


All character strings that are passed to the APIs must be null-terminated unless you explicitly provide the 
length, if a length field is available. 


If you are building a PDU to go to a remote agent, you must remember to do correct translation of strings. 
The iSeries server is an EBCDIC system, whereas an SNMP agent on an RISC System/6000®) 
(RS/60008)) computer is an ASCII system. Therefore, you must provide string values as you would see 
them on that system. For example, if you are sending a PDU to an RS/6000 system and the community 
name is public, you would enter the community name string in hexadecimal, X'7075626C6963'. See the 
data conversion APIs to convert data from EBCDIC to ASCII and vice versa. 


These APIs are blocked, which means that on a call to the API a PDU is sent across a communications 
protocol to an SNMP agent on a local or remote system. The call returns when a response has been received 
from the agent or when the command times out. On the return, all returned data is placed in the appropriate 
locations. You need do no further action to retrieve such data. 


Related Information 
e The <qtomeapi.h> file (see Header Files for UNIX-Type Functions) 


e snmpGetnext()--Retrieve Next MIB Object 


e@ snmpSet()--Set MIB Objects 


Example 


For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example. 
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snmpGetnext()--Retrieve Next MIB Object 


Syntax 


#include <qtomeapi.h> 


int snmpGetnext(snmppdu * pdu_ptr, 
char * host_ptr, 
unsigned long int time_out, 
char * comm_ptr, 
unsigned long int comm_len); 


Service Program Name: QTOMEAPI 


Default Public Authority: *USE 


Threadsafe: No 


An SNMP managing application uses the snmpGetnext() function to get the value of one or more 
management information base (MIB) objects from an SNMP agent or subagent on a local or remote system. 
The snmpGetnext() function gets the value of the object instance that is next in lexicographic order. 


Parameters 


pdu_ptr 


(Input) A pointer to a structure of the protocol data unit (PDU) type as defined in the 
<qtomeapi.h> file. 


This structure contains the PDU type (GET NEXT in this instance), the error status, the error index, 
and the pointer to the varbind structure. 


The varbind structure (found in the qtomeapi.h file) consists of the following: 


struct _varBind{ 
struct _varBind * next; 
char *oid; /* Null Terminated */ 
unsigned char asn_type; 
int val_len; 
union { 
int * int_val; 
char * str_val; 
} val; 


}; 
The fields for this structure are described as follows: 


*next The pointer to the next varbind. This has to be NULL if it is the last varbind in the 
list. 


*oid The pointer to the OID being set or retrieved (depending on the operation). 


asn_type The ASN type of the OID. This field must be set by the user only for the snmpSet 
function. On the snmpGet or snmpGetnext function, it is returned by the API. 


val_len For the snmpSet function, the user must set this to reflect the exact amount of data to 
be written to the OID. On an snmpGet or snmpGetnext, the user must use this field to 
indicate how much space to allocate for the value being retrieved. If the value coming 
back is greater than the amount of space allocated, a return code of 1 is received. 


val A union of either a pointer to the string data or a pointer to the integer data. This 
space is allocated by the user. 


host_ptr 
(Input) A pointer to the character string that contains the Internet Protocol (IP) address. 
This parameter can be stored in dotted decimal notation, that is, 9.130.38.217, or in host address 
format, that is, oursystem.endicott.ibm.com. This parameter must contain printable characters only. 
time_out 
(Input) The time-out value. 
This parameter is the amount of time in seconds that the management application is willing to wait 
for the response PDU. The minimum value is 1, and the maximum is 100. 
comm_ptr 
(Input) A pointer to the character string that contains the community name. 
This parameter contains a variable-length field that contains printable and nonprintable values. 
Therefore, the user must supply the exact length of this value in another parameter. 


EBCDIC-to-ASCI translation will not be done, and it is the responsibility of the managing 
application to specify the community name in the correct notation for the SNMP agent system. 


comm_len 


(Input) The length of the community name. 


This parameter is the exact length of the community name. The minimum value is 1, and the 
maximum is 255. 


Authorities 


Service Program Authority 
*USE 


Return Value 


The following are the possible return codes posted by the snmpGetnext() function: 
0 API_RC_OK 


snmpGetnext() was successful. 


4 


-9 


-10 


-1] 


-12 


-13 


-18 


-103 


-104 


-108 


API_RC_OUT_OF_MEMORY 


There was not enough storage to complete this operation. 


API_RC_OUT_OF_BUFFERS 


There were not enough internal buffers to continue. 


API_RC_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. 


API_RC_SNMP_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. This return code is equivalent to the 
-6 return code. 


API_RC_SNMP_INVALID_OID 


The OID specified in the varbind list is not valid. This return code is equivalent to the -112 return 
code. 


API_RC_INVALID_VALUE 

The specified value in the varbind is not valid. 
API_RC_INVALID_VALUE_REP 

The specified value in the varbind is incorrectly represented. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to decode the incoming PDU. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to encode the PDU data structure. 
API_RC_TIMEOUT 

A response to this request was not received within the allotted time-out value. 
API_RC_INVALID_PDU_TYPE 

The PDU type was not recognized as one of the seven common PDU types. 
API_RC_INVALID_IP_ADDRESS 

The IP address that was specified is not valid. 
APTI_RC_INVALID_COMMUNITY_NAME 

_ LENGTH 

The community name length must be greater than 0 and less than 256. 
API_RC_INVALID_TIMEOUT_PARM 


The time-out value must be greater than 0 and less than or equal to 100. 


-110 


-112 


-113 


-114 


-115 


-201 


-202 


241 


242 


243 


API_RC_UNKNOWN_HOST 

The host name or IP address that is specified is not known on the network. 
API_RC_INVALID_OID 

The OID that is specified in the varbind list is not valid. 
API_RC_INVALID_PDU_POINTER 

The pointer value to the PDU structure must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the host address must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the community name must be non-NULL. 
API_RC_SOCKET_ERROR 

The APIs have detected a socket error and cannot continue. 
API_RC_NOT_OK 

The APIs have detected an unknown error and cannot continue. The val_len field of the varbind 


structure contains a value that is not valid. 


APTI_RC_VAL_LEN_LESS_THAN_RETURNED __ 
VAL_LEN 


The value being returned by the API is greater than the space allocated by the user. 
API_RC_DOMAIN_ERROR 
This is equivalent to an MCH6801 error--stating object domain error. 


API_RC_INVALID_POINTER 


This is equivalent to an MCH3601 error--referenced location in a space does not contain a 
pointer. 


API_RC_INVALID_PTR_TYPE 


This is equivalent to an MCH3602 error-pointer type not valid for requested operation. 


For more information, see "Problem Determination for SNMP Manager APIs" in the Simple Network 


a 
Management Protocol ~ book. 


Error Conditions 


Following are the possible error statuses returned in the error status field of the PDU structure. These values 
are returned by the SNMP agents. 


O APILSNMP_ERROR_noError 
The function was successful. 
I API_SNMP_ERROR_tooBig 
The agent could not fit the results of an operation into a single SNMP message. 
2 APISNMP_ERROR_ noSuchName 
The requested operation identified an unknown variable name. 
3 APILSNMP_ERROR _badValue 


The requested operation specified an incorrect syntax or value when the management application 
tried to modify a variable. 


5 API_SNMP_ERROR_ genErr 


A nonspecific error occurred while running this operation on the SNMP agent. 


Usage Notes 


The area where the data is returned is the responsibility of the user, not the API. To allocate storage, the 
user may use the AddVarbind routine (see AddVarbind Routine). To deallocate storage, the user may use 


the FreePdu routine (see FreePdu Routine). 


You must use the correct PDU type on AddVarbind. It must match the operation on which you call. For 
example, if you build a PDU wherein AddVarbind passes a PDU type of Set and then you call the snmpGet 
operation using the PDU that you just created with Set, you will receive an error on the snmpGet call. 


All character strings that are passed to the APIs must be null-terminated unless you explicitly provide the 
length, if a length field is available. 


If you are building a PDU to go to a remote agent, you must remember to do correct translation of strings. 
The iSeries server is an EBCDIC system, whereas an SNMP agent on an RISC System/6000 (RS/6000) 
computer is an ASCII system. Therefore, you must provide string values as you would see them on that 
system. For example, if you are sending a PDU to an RS/6000 system and the community name is 
public, you would enter the community name string in hexadecimal, X'7075626C6963'. See the data 
conversion APIs to convert data from EBCDIC to ASCII and vice versa. 


These APIs are blocked, which means that on a call to the API a PDU is sent across a communications 
protocol to an SNMP agent on a local or remote system. The call returns when a response has been received 
from the agent or when the command times out. On the return, all returned data is placed in the appropriate 
locations. You need do no further action to retrieve such data. 


Related Information 
e The <qtomeapi.h> file (see Header Files for UNIX-Type Functions) 


e snmpGet()--Retrieve MIB Objects 


e@ snmpSet()--Set MIB Objects 


Example 


For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example. 
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snmpSet()--Set MIB Objects 


Syntax 


#include <qtomeapi.h> 


int snmpSet(snmppdu * pdu_ptr, 
char * host_ptr, 
unsigned long int time_out, 
char * comm_ptr, 
unsigned long int comm_len) ; 


Service Program Name: QTOMEAPI 


Default Public Authority: *USE 


Threadsafe: No 


An SNMP managing application uses the snmpSet() function to set one or more management information 
base (MIB) objects in an SNMP agent or subagent on a local or remote system. 


Parameters 


pdu_ptr 


(Input) A pointer to a structure of the protocol data unit (PDU) type as defined in the 
<qtomeapi.h> file. 


This structure contains the PDU type (SET in this instance), the error status, the error index, and the 
pointer to the varbind structure. 


The varbind structure (found in the qtomeapi.h file) consists of the following: 


struct _varBind{ 
struct _varBind * next; 
char *oid; /* Null Terminated */ 
unsigned char asn_type; 
int val_len; 
union { 
int * int_val; 
char * str_val; 
} val; 


}; 
The fields for this structure are described as follows: 


*next The pointer to the next varbind. This has to be NULL if it is the last varbind in the 
list. 


*oid The pointer to the OID being set or retrieved (depending on the operation). 


asn_type The ASN type of the OID. This field must be set by the user only for the snmpSet 
function. On the snmpGet or snmpGetnext function, it is returned by the API. 


val_len For the snmpSet function, the user must set this to reflect the exact amount of data to 
be written to the OID. On an snmpGet or snmpGetnext, the user must use this field to 
indicate how much space to allocate for the value being retrieved. If the value coming 
back is greater than the amount of space allocated, a return code of 1 is received. 


val A union of either a pointer to the string data or a pointer to the integer data. This 
space is allocated by the user. 


host_ptr 
(Input) A pointer to the character string that contains the Internet Protocol (IP) address. 
This parameter can be stored in dotted decimal notation, that is, 9.130.38.217, or in host address 
format, that is, oursystem.endicott.ibm.com. This parameter must contain printable characters only. 
time_out 
(Input) The time-out value. 
This parameter is the amount of time in seconds that the management application is willing to wait 
for the response PDU. The minimum value is 1, and the maximum is 100. 
comm_ptr 
(Input) A pointer to the character string that contains the community name. 
This parameter contains a variable-length field that contains printable and nonprintable values. 
Therefore, the user must supply the exact length of this value in another parameter. 


EBCDIC-to-ASCI translation will not be done, and it is the responsibility of the managing 
application to specify the community name in the correct notation for the SNMP agent system. 


comm_len 


(Input) The length of community name. 


This parameter is the exact length of the community name. The minimum value is 1, and the 
maximum is 255. 


Authorities 


Service Program Authority 
*USE 


Return Value 


The following are the possible return codes posted by the snmpSet() function: 
0 API_RC_OK 


snmpSet() was successful. 


4 


-9 


-10 


-1] 


-12 


-13 


-18 


-103 


-104 


-108 


API_RC_OUT_OF_MEMORY 


There was not enough storage to complete this operation. 


API_RC_OUT_OF_BUFFERS 


There were not enough internal buffers to continue. 


API_RC_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. 


API_RC_SNMP_OUT_OF_VARBINDS 


The maximum number of allowable varbinds was exceeded. This return code is equivalent to the 
-6 return code. 


API_RC_SNMP_INVALID_OID 


The OID specified in the varbind list is not valid. This return code is equivalent to the -112 return 
code. 


API_RC_INVALID_VALUE 

The specified value in the varbind is not valid. 
API_RC_INVALID_VALUE_REP 

The specified value in the varbind is incorrectly represented. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to decode the incoming PDU. 
API_RC_DECODE_ERROR 

The SNMP APIs were unable to encode the PDU data structure. 
API_RC_TIMEOUT 

A response to this request was not received within the allotted time-out value. 
API_RC_INVALID_PDU_TYPE 

The PDU type was not recognized as one of the seven common PDU types. 
API_RC_INVALID_IP_ADDRESS 

The IP address that was specified is not valid. 
APTI_RC_INVALID_COMMUNITY_NAME 

_ LENGTH 

The community name length must be greater than 0 and less than 256. 
API_RC_INVALID_TIMEOUT_PARM 


The time-out value must be greater than 0 and less than or equal to 100. 


-110 


-112 


-113 


-114 


-115 


-201 


-202 


241 


242 


243 


API_RC_UNKNOWN_HOST 

The host name or IP address that is specified is not known on the network. 
API_RC_INVALID_OID 

The OID that is specified in the varbind list is not valid. 
API_RC_INVALID_PDU_POINTER 

The pointer value to the PDU structure must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the host address must be non-NULL. 
API_RC_INVALID_HOST_POINTER 

The pointer value to the community name must be non-NULL. 
API_RC_SOCKET_ERROR 

The APIs have detected a socket error and cannot continue. 
API_RC_NOT_OK 

The APIs have detected an unknown error and cannot continue. The val_len field of the varbind 


structure contains a value that is not valid. 


APTI_RC_VAL_LEN_LESS_THAN_RETURNED __ 
VAL_LEN 


The value being returned by the API is greater than the space allocated by the user. 
API_RC_DOMAIN_ERROR 
This is equivalent to an MCH6801 error--stating object domain error. 


API_RC_INVALID_POINTER 


This is equivalent to an MCH3601 error--referenced location in a space does not contain a 
pointer. 


API_RC_INVALID_PTR_TYPE 


This is equivalent to an MCH3602 error--pointer type not valid for requested operation. 


For more information, see "Problem Determination for SNMP Manager APIs" in the Simple Network 


a 
Management Protocol ~ book. 


Error Conditions 


Following are the possible error statuses returned in the error status field of the PDU structure. These values 
are returned by the SNMP agents. 


O APILSNMP_ERROR_noError 
The function was successful. 
I API_SNMP_ERROR_tooBig 
The agent could not fit the results of an operation into a single SNMP message. 
2 APISNMP_ERROR_ noSuchName 
The requested operation identified an unknown variable name. 
3 APILSNMP_ERROR _badValue 


The requested operation specified an incorrect syntax or value when the management application 
tried to modify a variable. 


5 API_SNMP_ERROR_ genErr 


A nonspecific error occurred while running this operation on the SNMP agent. 


Usage Notes 


The area where the data is returned is the responsibility of the user, not the API. To allocate storage, the 
user may use the AddVarbind routine (see AddVarbind Routine). To deallocate storage, the user may use 


the FreePdu routine (see FreePdu Routine). 


You must use the correct PDU type on AddVarbind. It must match the operation on which you call. For 
example, if you build a PDU wherein AddVarbind passes a PDU type of Set and then you call the snmpGet 
operation using the PDU that you just created with Set, you will receive an error on the snmpGet call. 


All character strings that are passed to the APIs must be null-terminated unless you explicitly provide the 
length, if a length field is available. 


If you are building a PDU to go to a remote agent, you must remember to do correct translation of strings. 
The iSeries server is an EBCDIC system, whereas an SNMP agent on an RISC System/6000 (RS/6000) 
computer is an ASCII system. Therefore, you must provide string values as you would see them on that 
system. For example, if you are sending a PDU to an RS/6000 system and the community name is 
public, you would enter the community name string in hexadecimal, X'7075626C6963'. See the data 
conversion APIs to convert data from EBCDIC to ASCII and vice versa. 


These APIs are blocked, which means that on a call to the API a PDU is sent across a communications 
protocol to an SNMP agent on a local or remote system. The call returns when a response has been received 
from the agent or when the command times out. On the return, all returned data is placed in the appropriate 
locations. You need do no further action to retrieve such data. 


Related Information 
e The <qtomeapi.h> file (see Header Files for UNIX-Type Functions) 


e snmpGet()--Retrieve MIB Objects 


e@ snmpGetnext()--Retrieve Next MIB Object 


Example 


For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example. 
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Using SNMP Manager APIs--Example 


The examples in this topic provide two small routines that may aid in the use of several SNMP manager 
APIs. In addition, a sample snmpGet loop is provided to show the use of the two sample programs and its 
relation to an snmpGet call. 


These examples are for the SNMP manager APIs snmpGet, snmpSet, and snmpGetnext. 


See Code disclaimer information for information pertaining to code examples. 


AddVarbind Routine 


This routine is used to create an initial protocol data unit (PDU), and subsequent calls will add varbinds to 
that PDU. 


The value of this routine is that you will be able to create PDUs and add varbinds to those PDUs. The 
burden of storage allocation for each varbind and its values is removed from you, as is pointer maintenance 
on the varbinds. Remember that you need to deallocate any dynamic storage when you are done with it. The 
FreePdu routine (see page FreePdu Routine) is an easy way to do this. The AddVarbind sample code 


follows: 


#include <qtomeapi.h> 


int AddVarbind(snmppdu **pdu, char * oid, value v, unsigned 
char pdu_type, unsigned char asn_type) 


{ 


varBind * t; /* Varbind pointer. a7; 
int str_len,i; 


switch ( pdu_type ) { /* Check to make sure that*/ 
case GET_PDU_TYPE: /* the PDU type is a known*/ 
case SET _PDU_TYPE: /* value. If not, the */ 
case GETNEXT_PDU_TYPE: break; /* you may want to set a */ 
defaults: return(-2005); /* return code value of */ 
/* your liking (for sy 
} /* example, -2005). */ 
if (pdu[0] == NULL || 
pdu[0] == 0 || 
pdu[0] == '\0') 
{ /* Check if PDU is null (meaning new PDU).*/ 
pdu[0] = ( snmppdu *) malloc(sizeof(snmppdu) ); 
/* Allocate storage for the PDU. ay, 
memset ( (snmppdu *) pdu[0],0,sizeof(pdu[0])); 
/* Initialize the PDU to zeros. a] 
pdu[0]->pdu_type = pdu_type; 
/* Initialize the PDU type. ard 
pdu[0]->varbind = ( varBind * ) malloc(sizeof (varBind) ); 
/* Allocate storage for the varbind. a7] 
str_len = strlen(oid); 


/* Set the length of the OID. */ 


if (str_len > API_MAX OID_SIZE ) return(-2000); 
/* If OID length is not valid return. avs 
pdu[0]->varbind->oid = 


(char *) malloc (API_MAX OID_SIZE+1); 
strcpy (pdu[0]->varbind->oid, oid); /* Copy the 
OID.*/ 
pdu[0]->varbind->oid[str_len] = '\0'; 
/*Null terminate OID.*/ 
pdu[0]->varbind->next = NULL; /* Nullify next 
pointer.*/ 
/* This signifies last varbind.*/ 
t = pdu[0]->varbind; /* Set temporary pointer to 
varbind.*/ 
t->val.str_val = 
(char *) malloc (API_MAX_VALUE_SIZE+1); /*Allocate storage */ 


/* for the value of the OID.*/ 
[RK KK KR KK KK KK KK I I I II I I KK KK / 


/* Note: This sample code shows a malloc of the maximum value size */ 
/* plus 1 for null termination. It would be in your best interest AY 
/* to allocate only the amount of the actual value, plus 1. This Fa): 
/* reduces the amount of space allocated on each PDU. &/ 


[BRK KKK KK KK KR KK I I I I KK KK / 


} 


else 
{ 
if ( pdu[0]->pdu_type != pdu_type ) \keyword{return(-2001); 
/* If this is not the initial call to */ 
/* add a varbind, then check to make */ 
/* sure the PDU type of this call 7] 
/* matches the original. */ 
t = pdu[0]->varbind; 
/* Store temporary pointer to this varbind.*/ 
i = 0; /* Initialize loop variable. ay A 
while ( t->next != NULL ) /* Loop until you locate last varbind.*/ 
{ 
t = t->next; 
itt; 
} 
if ( i > 100 /* MAX_NUM... */ ) \keyword{return(-2002); 
/* Return if you exceed maximum varbinds. */ 
t->next = ( varBind * ) malloc(sizeof(varBind) ); 
/* Allocate storage for this varbind. */ 
t = t->next; /* Set new temporary varbind pointer. * / 
str_len = strlen(oid); /* Set length of OID. */ 


if (str_len > API_MAX OID_SIZE ) return(-2000); 
/* If OID length exceed maximum, return. */ 
t->oid = (char *) malloc (API_MAX _OID_SIZE+1); 
/* Allocate storage for the OID. */ 
strcpy (t->oid, oid); 
/* Copy OID to storage. */ 


t->oid[str_len] = '\0'; 


/* Null terminate the OID. */ 
t->val.str_val = (char *) malloc (API_MAX VALUE_SIZE+1); 
/* Allocate storage to hold value. */ 


t->val_len = API_MAX _VALUE_SIZE+1; 
[ORR III III RII III III III III I IOI I AOI I A IIASA IIASA IIa a a oe / 


/* Note: This sample code shows a malloc of the maximum value size eA 
/* plus 1 for null termination. It would be in your best interest */ 
/* to allocate only the amount of the actual value, plus 1. This * / 
/* reduces the amount of space allocated on each PDU. */ 


[BRK KKK KK KK KK KK I I I I I I I I / 
t->next = NULL; 


/* Nullify next varbind pointer ff 

} /* signifying the last varbind. Hf 

if ( pdu_type == SET_PDU_TYPE ) /* For sets only * / 
{ 

t->asn_type = asn_type; /* Save ASN type * / 


switch (asn_type) { 
case API_ASN_OCTET_STRING: /* All string types a 
case API_ASN_OBJECT_IDENTIFIER: 
case API_ASN_IpAddress: 
case API_ASN_ Opaque: 


str_len = strlen(v.str_val); /* Store length */ 
strecpy (t->val.str_val,v.str_val); /* Copy string * / 
t->val.str_val[str_len] = '\0O'; 

/* Null terminate */ 
t->val_len = str_len; /* Save length * / 
break; 


case API_ASN_INTEGER: 
case API_ASN_Counter: 
case API_ASN_Gauge: 
case API_ASN_TimeTicks: 


*t->val.int_val = *v.int_val; /* Save integer value */ 
t->val_len = sizeof(int); /* Save length of */ 
break; /* an integer. */ 


default: return(-2003); 
} 


} 
return (API_RC_OK) ; 


FreePdu Routine 


This routine is used to free all the dynamically allocated storage from AddVarbind. 


The value of this routine is that you can free all the dynamically allocated (user domain) storage with one 
call. The FreePdu sample code follows: 


#include <qtomeapi.h> 


void FreePdu(snmppdu * pdu) /* Pass in pointer to PDU. xf} 


varBind * vb, *t; /* Define pointers to varbinds. * / 


vb = pdu->varbind; /* Set first varbind pointer. * / 

while (vb != NULL) { /* Loop as long as varbinds exist. x] 
t = vb; /* Save current varbind pointer. */ 
vb = vb->next; /* Pointer to next varbind. */ 
free (t->oid); /* Free storage allocated for OID. ey, 
free (t->val.str_val); /* Free storage allocated for value. * / 
free (t); /* Free storage allocated for temporary varbind. */ 

} 

free (pdu) ; /* Free storage allocated for PDU. */ 


snmpGet Call Example 


When you use the following example to call the snmpGet, snmpSet, or snmpGetnext API, it is important to 
note the following: 


The area where the data is returned is the responsibility of the user, not the API. To allocate 
storage, the user may use the AddVarbind routine (see AddVarbind Routine). To deallocate 


storage, the user may use the FreePdu routine (see FreePdu Routine). 


You must use the correct PDU type on AddVarbind. It must match the operation on which you call. 
For example, if you build a PDU wherein AddVarbind passes a PDU type of Set and then you call 
the snmpGet operation using the PDU that you just created with Set, you will receive an error on 
the snmpGet call. 


All character strings that are passed to the APIs must be null-terminated unless you explicitly 
provide the length, if a length field is available. 


If you are building a PDU to go to a remote agent, you must remember to do correct translation of 
strings. The iSeries server is an EBCDIC system, whereas an SNMP agent on an RISC 
System/6000 (RS/6000) computer is an ASCII system. Therefore, you must provide string values 
as you would see them on that system. For example, if you are sending a PDU to an RS/6000 
system and the community name is public, you would enter the community name string in 
hexadecimal, X'7075626C6963'. 


These APIs are blocked, which means that on a call to the API a PDU is sent across a 
communications protocol to an SNMP agent on a local or remote system. The call returns when a 
response has been received from the agent or when the command times out. On the return, all 
returned data is placed in the appropriate locations. You need do no further action to retrieve such 
data. 


The snmpGet sample code follows: 


#include <qtomeapi.h> 


void main() { 


typedef union 


int * int_val; 
char * str_val; 


} value; /* Value typedef. */ 
snmppdu *pdu; /* PDU pointer. */ 
value Vv; /* Value container. * / 
int rc; /* Return code. * / 
char community_name[120]; /* Community container. */ 
pdu = NULL; /* Nullify PDU pointer. a] 
re = AddVarbind (&pdu, /* Add varbind with */ 

"1.3.6.1.2.1.1.1.0", /* OID, value, type of a] 
Vv, /* PDU this is for, ASN */ 
GET_PDU_TYPE, /* type. PDU pointer */ 
0); /* is set to non-null. * 
if (re <0) f{ /* Check error code user */ 
printf("Error: %$d\n",rc); /* defined here. Sample */ 
exit (1); /* is print return code. */ 
} 
re = AddVarbind(&pdu, /* Add second varbind. */ 
W413 Oe 26 dT /* PDU pointer is now Lair A 
Vv, /* non-null after lst Bar 
GET_PDU_TYPE, /* invocation of Add- AY 
0); /* Varbind. * / 
if (re <0) f{ 
printf("Error: %d\n",rc); /* Again, check return code. */ 
exit(1); 
} 
strcepy (community_name, "public"); /* Set community name. */ 
re = snmpGet (pdu, /* Invoke operation. yf 
"system_name_of_snmp_agent_system", /* Hostname. * / 
10, /* Time-out value. af 
community_name, /* Pointer to community name. */ 
6); /* Correct length of * / 
} /* community name. * / 
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SNMP Trap Support 


You can monitor for unsolicited SNMP trap messages by using the SNMP trap support. These trap messages may contain 
helpful data for managing a network. 


By using the OS/400 SNMP manager, it is possible to deliver SNMP traps to data queues. All traps that are received on an 
iSeries server can be routed to user-defined data queues as shown in Figure: SNMP Trap Support. Your applications 


should monitor the data queue to receive trap information. 


SNMP Trap Support 


Trap Received on 05/400 


re User-Defined Application 
Data Queue Programs 


Client Configuration 
and Management 


Configuring Trap Support 


SNMP trap support uses the exit point QIBM_QZCA_SNMPTRAP and a data queue that you define. To use SNMP trap 
support, do the following: 


1. Use the Work with Registration Information (WRKREGINF) command to determine if the 
QIBM_QZCA_SNMPTRAP exit point exists on your system (see Figure 1-3). If the exit point does not exist, 
create and register the exit point by using this command: 


CALL PGM(QUSRGPT) 
PARM ('QIBM_QZCA_SNMPTRAP  ! 
"ZCATO100' X'00000000' X'00000000') 


Note: The first parameter must be 20 characters long. 


2. Define a data queue of 32780 bytes. For example, to define a data queue that is called MYQUEUE in library 
QGPL, enter: 


CRIDTAQ DTAQ(QGPL/MYQUEUE) MAXLEN (32780) 


3. Register the exit program and exit program data with the QIBM_QZCA_SNMPTRAP exit point by using the 
Work with Registration Information (WRKREGINF) command. For example, see Figure: Work with Registration 


Information (WRKREGINF) Display through Figure 1-6. 


This configuration only registers the data queue name. You may want to add the program name and library that will use 
this data queue even though this information is not used by the system. 


Figure: Work with Registration Information (WRKREGINF) Display 


Work with Registration Information 


Type options, press Enter. 


5=Display exit point 8=Work with exit programs 


Exit 
Exit Point 
Opt Point Format Registered Text 
OQIBM OTA TAPE TMS TMS00200 *YES 
QIBM_OTF_TRANSFER TRANO100 *YES Original File Transfer 
Functi | 
OQIBM_QVP_PRINTERS PRNTO100 *YES Original Virtual Print 
Server | 
QIBM_QZCA_ADDC ZCAA0100 *YES Add Client exit point 
QIBM _QOZCA_REFC ZCAF0100 *YES Refresh Client 
Information ex | 
QIBM_QOZCA_RMVC ZCARO0100 *YES Remove Client exit point 
8 QIBM OZCA_SNMPTRAP ZCAT0O100 *YES 
QIBM_QZCA_UPDC ZCAU0100 *YES Update Client Information 
exi | 
QIBM_QOZDA_INIT ZDAT0100 *YES Database Server - entry 
QIBM_OZDA NDB1 ZDAD0100 *YES Database Server - 
database a | 
| QIBM_QOZDA NDB1 ZDAD0200 *YES Database Server - 


database a | 


More... | 
Command 


F3=Exit F4=Prompt F9=Retrieve F12=Cancel 


Figure: Work with Exit Programs Display is reached using Option 8 from the display shown in the Figure above. 


Figure: Work with Exit Programs Display 


| Work with Exit Programs 


Exit point: QIBM_OZCA_SNMPTRAP Format: ZCATO100 


Type options, press Enter. 


1=Add 4=Remove 5=Display 10=Replace 


Exit 
Program Exit 
Opt Number Program Library 


1 TRAPCHECK OGPL 
(No exit programs found.) 


F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel 


Figure: Add Exit Programis reached using Option | from the Figure above and pressing F10 for additional parameters. 


Figure: Add Exit Program - Display 1 of 2 


Add Exit Program (ADDEXITPGM) 


Type choices, press Enter. 


Exit point ....... . . . . > QIBM_QZCA_SNMPTRAP 


Exit point format > ZCATO100 Name 
Program. Number... 4 ga ee cd Se 1-2147483647, *LOW, *HIGH 
Program ........ . . . . > TRAPCHECK Name 
Ta DVaArY ge <3 ee ce ae Go ch le See ah Se QGPL Name, *CURLIB 
TEXt. "GESCTIPETON sock Y xe aw Os Reroute traps 


Additional Parameters 


Replace existing entry .... .> *NO *YES, *NO 

Create exit point ....... *NO *YES, *NO 
More... | 
| F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this 
display | 


F24=More keys 


Add Exit Program (ADDEXITPGM) 


Type choices, press Enter. 


Exit program data: 


Coded character set ID.... *NONE Number, *NON 


Gl 


, *JOB 


Program data ......... QGPL/MYQU 


Gc 


Length of data ........ *CALC 0-2048, *CALC 


| F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this 
display | 
F24=More keys 


Notes: 


1. The program data field on the Add Exit Program (ADDEXITPGM) display contains the library name and the data 
queue name that will be used by the trap manager. This data must not exceed 21 bytes. 


2. The exit program and library do not have to exist when they are added to the exit point. 


3. The format for the ZCATO100 trap data queue entry follows. For details about the SNMP trap, refer to the Internet 
standard for the trap message described in RFC 1155 and RFC 1157. The values for the object type field can be 
found in OS/400 library QSYSINC, file H, member QTOMEAPI. 


| Offset 
| Dec Hex /|Type Field 


| 0 0 |[CHAR(0) Entry type (always *SNMPTRAP) 
| 10 A [CHAR(2) Entry ID (currently 01) 


12 C BINARY(4) Version (This is the start of the trap header. All 
displacements are from the start of the trap 
header.) 

| 16 10 [BIN ARY(4) Length of community name 

| 20 14 [BIN ARY(4) Displacement to community name 
24 18 [BIN ARY(4) Length of enterprise object ID 

| 28 1c [BIN ARY(4) Displacement to enterprise object ID 
| 32 20 [BIN ARY(4) Length of agent address 

| 36 24 [BIN ARY(4) Displacement to agent address 

| 40 28 [BIN ARY(4) Generic trap type 

| 44 2C [BIN ARY(4) Specific trap code 


[ 52 [ 34 |BINARY(4) [Number of variablebindings = 
| 56 | 38 |BINARY(4) {Displacement to first variable binding = 
Note: An array of variable bindings follows. 

[BINARY(4) [Lengthofobjectname =————s 
[BINARY(4) [Displacement to objectname = 
[BINARY(4) [Lengthofvalue 
[BINARY(4) [Displacementto value 


BINARY(4) Value type (Values for this field can be found in 
OS/400 library QSYSINC, file H, member 
QTOMEAPTI.) 


Note: All object names and values follow. 


CHAR(*) Object names and values for all variable 
bindings 


4. The library name and data queue must be specified in uppercase on the exit point. 


5. Multiple exit programs are supported on the QIBM_QZCA_SNMPTRAP exit point. Each exit program must 
contain only one data queue. 


6. A maximum of 100 data queues can be defined. 


7. The data queue names are retrieved from the exit point only when the trap manager is started. To activate any 
changes to the data queues, you must end the trap manager with the End Trap Manager (ENDTRPMGR) 
command and restart the trap manager with the Start Trap Manager (STRTRPMGR) command. 


8. In the preceding scenario, all traps are added to the data queue. If the queue is locked, damaged, destroyed, or 
named incorrectly, the traps are lost. It is the responsibility of the user application to remove traps from the queue. 
No messages are sent if the queue is full or traps not removed. 
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Header Files for UNIX-Type Functions 


Programs using the UNIX-type functions must include one or more header files that contain information 
needed by the functions, such as: 


e Macro definitions 
e Data type definitions 
e Structure definitions 
e Function prototypes 
The header files are provided in the QS YSINC library, which is optionally installable. Make sure 


QSYSINC is on your system before compiling programs that use these header files. For information on 
installing the QSYSINC library, see Data structures and the QSYSINC Library. 


The table below shows the file and member name in the QS YSINC library for each header file used by the 
UNIX-type APIs in this publication. 


Name of File in 
Name of Header File QSYSINC Name of Member 


[| arpa/ineth [| arpa/ineth [ ARPA [INET 


a 
a * 

tik | | so 
[  —sbseerrch CEC A~<“‘i‘~*Y:S*é‘éiBSEERRR 
[ss direnth [CM Rs—~<“i«i‘Cé«zYS)~OCéIRENT 
[ emoh [| H [ERRNO] | 
[_eph | SOS 

| evinttypes. h | | TNS 
ee ee ee 
[| %netinet/iemp6.h NETINE |  ICMP6& 
[| netinetinh NETINET [| WN 
| netinet/ip_icmp.h NETINET [|  IPICMP 


mo) oo) eo) eo) a) ee} ee} ey] 


| netinet/ip.h NETINET | IP 
| 2’netinet/ip6.h NETINET | IP6& 
| netinet/tcp.h NETINET TCP 


| netinet/udp.h NETINET UDP 

[netns/idph = | 0S NETNS) [CIDP 
[netns/ipxh = |S NETNS) [CPX 
[so netns/ns-h | NETNS) [CONST 
[so netns/sp-b |S NETNS) [SP 
[netrouteh = [)CNET)=—~<C;«é‘L”)~Ss*'<‘éROUTEECi:*s 
[—snettel/telLh «= sis[))sSNETTEL =o [)ti‘<‘STENRES—“( isis 


an 


[  oosh fC OS2 

[|  —sosddefh fC ASE S2DEF 
[ pwd fC PWD 

[0 gh fH QLG 

| —s qpOlfloph fs QPOLFLOP 
| Bqp0limih | | QPOLIRNLE 

| 2>qpOlror.h | | QPOLROR& 

|  qpOzolsm-h fC HH—C*ST ss QPOZOLSM 
| — qpOztrech fC QPOZTRE 
|  qpOztrmlh [| CSTs QPOZTRML 
| #qsoasync.h | | QSOASYNC% 
| qtnxaapi.h | QTNXAAPI 
[ qtnxadtph fC H——CSE ss QQTNXADTP 
|  qtomeapih sf] CM ™—C~@TSsC QQOMEEAP 


TRIG 


| qtossapi.h | H | QTOSSAPI 
| resolv.h | H | RESOLVE 


an 


| semaphore.h | | SEMAPHORE 


[signal | CMHC SIGNAL 
[|  spawnh Cf CM ™~“<~S SPAWN 
[ssh fA SSL 

| sysferrnoh = fC H™:~iT SC ERRNOU 
[| sysfioctLh SYS [|  IOCTL 
| ——ssys/ipeh SYS [ woe 


| sys/layout.h | H | LAYOUT 
| sys/limits.h | H | LIMITS 


| —ssys/msg-ho SYS MSG 

[| sys/param.h SYS [ PARAM 
| #*sys/resource.h SYS | RESOURCE® 

| —ssys/sem-h SYS SEM 

| sys/setimp.h SYS | ‘SETIMP 
| sys/shm.h SYS SHM 

[| sys/signalh SYS [ SIGNAL 
[| _sys/socketh SYS [SOCKET 
[| —sys/stath SYS [ STAT” 


| sys/statvfs.h SYS | STATVFS 


| —ssysfimeh SYS [| TIME 
[| sys/types.b SYS [TYPES si 
| —ssys/uio.h SYS UIO 

[ sys SYS [ UN 
| —ssys/waith SYS | WAIT 
| Sulimit.h H | ULIMIT*& 

[| sounistdh fC HSE UNISTD 
[  soutimeh fC UTIME 


You can display a header file in QS YSINC by using one of the following methods: 


e Using your editor. For example, to display the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5) 


e Using the Display Physical File Member command. For example, to display the sys/stat.h header 
file, enter the following command: 


DSPPFM FILE(QSYSINC/SYS) MBR(STAT) 


You can print a header file in QSYSINC by using one of the following methods: 


e Using your editor. For example, to print the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION (6) 
e Using the Copy File command. For example, to print the sys/stat.h header file, enter the following 


command: 


CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR (STAT) 


Symbolic links to these header files are also provided in directory /QIBM/include. 
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Errno Values for UNIX-Type Functions 


Programs using the UNIX-type functions may receive error information as errno values. The possible 
values returned are listed here in ascending errno value sequence. 


[Name [Value [Test 

~——— a ee domain error occurred in a math 
function. 

[ERANGE = GE [300200 A [Arangeerror occurred. = error [Arangeerror occurred. = 

—| C _— Data was truncated on an input, output, or 
update operation. 

EN [ENOTOPEN [3004 [Fileisnotopen. is not [Fileisnotopen. 


—— OTREAD — [File i is not opened for read operations. 
EIO [3006 [Input/output error. 


EN [ENODEV [3007 N [Nosuchdevice. [Nosuchdevice. device. 

ae —_ Cannot get single character for files 
opened for record I/O. 

EN [ENOTWRITE [30090 [File is not opened for write operations. is not [File is not opened for write operations. for write operations. 


a —— [The stdin stream cannot be opened. 
[ESTDOUT [3011 [The stdout stream cannot be opened. 


[ESTDERR [30120 [The stderr stream cannot be opened. stderr stream cannot be [The stderr stream cannot be opened. 

_—| a The positioning parameter in fseek is not 
correct. 

[EBADNAME AME [30140 [The object name specified is not correct. — [The object name specified is not correct. — name specified is not correct. 


a ——! The type variable specified on the open 
function is not correct. 


[EBADPOS 3017s [The position specifier is not correct. position [The position specifier is not correct. is not correct. 


17 
EN a — There is no record at the specified 
position. 
ENUMMBRS 3019 Attempted to use ftell on multiple 
members. 
ENUMRECS 3020 The current record position is too long for 
ftell. 
EINVAL 3021 The value specified for the argument is not 
correct. 
EBADFUNC 3022 Function parameter in the signal function 
is not set. 
[302500 


EN [ENOENT T No [No such path or directory, = [No such path or directory, = or directory. 


FoR? ——— ht’ —— ae 
[EPERM  =——<CS~s«LB27_~——SSC«*d Phe Oplerationn is not permitted. = 
[EBADDATA  ——s[3028——Ss[Meessage dataisnotvalid. = 
[EBUSY ==—=«S(38029—s Resource busy, 
[EBADOPT —s*(3040 = Option specified is not valid. 
[ENOTUPD ~—s*([3041 =~‘ File is not opened for update operations. 
[ENOTDLT ~—*[3042. [File is not opened for delete operations. 


EPAD 3043 The number of characters written is 
shorter than the expected record length. 

EBADKEYLN 3044 A length that was not valid was specified 
for the key. 

EPUTANDGET 3080 A read operation should not immediately 
follow a write operation. 

EGETANDPUT 3081 A write operation should not immediately 
follow a read operation. 

[EIOERROR [3101 [A nonrecoverable I/O error occurred. 

[EIORECERR [3 102 [A recoverable I/O error occurred. 

[EACCES [3401 [Permission denied. 


[EN OTDIR [3403 [N ot a directory. 
[ENOSPC [3404 [No space is available. 


[EXDEV [3405 Improper link, [Improperlink, 


[34050 
aa_— 3406 Operation would have caused the process 
to be suspended. 
EWOULDBLOCK 3406 Operation would have caused the process 
to be suspended. 
[3407 


[EINTR [3407 SS s‘[Interrupted function call. [Interrupted function call. call. 


ee— 3408 The address used for an argument was not 
correct. 


[ETIME [3409 [3409 [Operation timedout. [Operation timedout. out. 
—_——— [3415 0 No [No such device oraddress. device [No such device oraddress. address. 
SEs i Pa 
failure 
[ERECURSE [3419 [Recursive attempt rejected. = attempt [Recursive attempt rejected. = 
 ORNESE Si —— see 
[EADDRNOTAVAIL [342200 [Address is notavailable. = [Address is notavailable. = not available. 
ESINOSUORT > pean type of socket is not supported in this 
protocol family. 
[EALREADY [342300 [3423 [Operation is already in progress. = is already in progress. 
REE ABORTED [34240000 [Connection ended abnormally. ended [Connection ended abnormally. 
25 


ECONNRTUSED — aS rma ba tn te 
connect operation 
i ae ce 
reset by that socket 
[EDESTADDRREQ. [3427 00 [3427 | Operation requires destination address. requires [Operation requires destination address. address. 
[EHOSTDOWN [3428s {Ar remote host is notavailable. 
[EHOSTUNREACH [3429 ‘A route to the remote host is not available. 
[EINPROGRESS —[3430. Ss |Operationin progress. = 
[EISCONN «(3431s {A connection has already been established. 
[EMSGSIZE «(3432s [Message size isoutofrange. 
[ENETDOWN  ——s[3433.—s*[ The network currently is not available. 


ENETRESET 3434 A socket is connected to a host that is no 
longer available. 


[ENETUN REACH [3435 [Cannot reach the destination network. 

ENOBUFS 3436 There is not enough buffer space for the 
requested operation. 

ENOPROTOOPT 3437 The protocol does not support the 

specified option. 

ENOTCONN 3438 Requested operation requires a 
connection. 

ENOTSOCK 3439 The specified descriptor does not 
reference a socket. 

[EN OTSUP [3440 [Operation is not supported. 

[EOPN OTSUPP [3440 [Operation is not supported. 


EPFNOSUPPORT 3441 The socket protocol family is not 
supported. 

EPROTONOSUPPORT |3442 No protocol of the specified type and 
domain exists. 

EPROTOTYPE 3443 The socket type or protocols are not 
compatible. 

ERCVDERR 3444 An error indication was sent by the peer 
program. 


[ESHUTDOWN [3445 [Cannot send data after a shutdown. 
[ESOCKTN OSUPPORT [3446 [The specified socket type is not supported. 


ETIMEDOUT 3447 A remote host did not respond within the 
timeout period. 

EUNATCH 3448 The protocol required to support the 
specified address family is not available at 
this time. 


[EBADF = =—S—=«&;3'45——SsDescriptorisnot valid, 
[EMFILE  =—S*[3452,—S——Ss {Too many open files for this process. 
[ENFILE =——=S&3453. Ss [Too many open files inthe system. 
EPIPE == ~—«*(3455, ss (Brokenpipe. 
[ECANCEL =——s«[3456.———s|Operationcancelled. = 
[EEXIST =———s«*(3'KST_—— sie exists, 
[EDEADLK =——s*[3459_ Resource deadlock avoided. 
[ENOMEM ——s«[3460—Ss« Storage allocation request failed. = 
62 


a 34 The synchronization object no longer 
exists because the owner is no longer 
running. 

EDESTROYED 3463 The synchronization object was destroyed, 
or the object no longer exists. 

[ETERM [3464 00—CO [3464 Operation was terminated. = was [Operation was terminated. = 


aes —— OENT1 [3 465 [N o such file or directory. 


ENOEQFLOG 3466 Object is already linked to a dead 
ones sag 


[EEMPTYDIR [3 467 [Directoryisempty. = is empty. 


EMLINK 3468 Maximum link count for a file was 
exceeded. 


ESPIPE  =—~SC~«&346—— “Seek request is not supported for object. 
[ENOSYS —————=«*3470.—S—SSs|Function not implemented. = 
[EISDIR ——i(ass—t*é«*BATALC Specified targetisadirectory, = 
[EROFS =———~—é«i;3B220-—— Read-only file system. 
[EUNKNOWN  —s[3474.— ss [Unknown system state. = 
[EITERBAD  =——s«(34750—— iterator isnotvalid. = 
[EITERSTE  =—sS*(3476 ~—S—SCs=|Iterator is in wrong state for operation. 
[EHRICLSBAD —s [3477 Ss HIRI classisnotvalid. 
[EHRICLBAD ~—s([3478 = {IRI subclassisnot valid. = 
[EHRITYPBAD —[3479 Ss {HRI typeisnotvalid, = 
[ENOTAPPL —=—s*[3480.—~——Ss [Datta requested is not applicable. = 
[EHRIREQTYP  =—[3481_ = {ARI request type isnot valid. 
[EHRINAMEBAD —_ [3482s {HRT resource name isnot valid. 
[EDAMAGE —s([3484.————s [A damaged object was encountered. 
[ELOOP  ———~™—=é«S;3485— SA cop exists in the symbolic links. 
[ENAMETOOLONG [3486 = {Apathnameistoolong, 
[ENOLCK = =——s«*(3487,——s No locksare available. = 
[ENOTEMPTY —*[3488 ~=——Ss[Directory isnotempty. = 
[ENOSYSRSC [3489s System resources are not available. = 
[ECONVERT =— [3490s |Conversionerror, 


[E2BIG [3491 [3491 Ss [Argumentlististoolong, [Argument lististoolong, = is too long. 
—=———— 3492 Conversion stopped due to input character 
that does not belong to the input codeset. 


[ETYPE  ——™ [3493 [3493 |Objecttypemismatche type [Object type mismatch, 
—— 3494 Attempted to reference a directory that 
was not found or was destroyed. 
EBADOBJ 3495 Attempted to reference an object that was 
not found, was destroyed, or was 
damaged. 
EIDXINVAL 3496 Data space index used as a directory is not 
valid. 
[ESOFTDAMAGE [3497 [3497 [Objecthas softdamage. [Objecthas softdamage. soft damage. 


Soe | OTENROLL 3498 User is not enrolled in system distribution 
ies sae———— 


[EOFFLINE = 3499 [3499 |Objectissuspended. is suspended. 


[34990 
oe —— [3 500 [Object i is a read-only object. 


EEAHDDSI 3501 Hard damage on extended attribute data 
space index. 

EEASDDSI 3502 Soft damage on extended attribute data 
space index. 

EEAHDDS 3503 Hard damage on extended attribute data 
space. 

EEASDDS 3504 Soft damage on extended attribute data 

| | ee 


[EEADUPRC [3505 [Duplicate extended attribute record. 


ELOCKED 3506 Area being read from or written to is 
locked. 


[EFBIG [3507 [3507 ss |Objecttoolarge. [Objecttoolarge, large. 
509 


a—_—— 3 The semaphore, shared memory, or 
message queue identifier is removed from 
the system. 

OMSG e The queue does not contain a message of 


the desired type and (msgflg logically 
ANDed with IPC_NOWAIT). 


[EFILECVT = [351k [File ID conversion of a directory failed. ID conversion of a [File ID conversion of a directory failed. failed. 

a——— _— A file ID could not be assigned when 
linking an object to a directory. 

[ESTALE [3513 [File handle was rejected by server. handle was [File handle was rejected by server. by server. 


es} — oes 
[ENOTSIGINIT ——[3516 [Process is not enabled for signals. 

[ECHILD  =———~—=«~S(;B'SS'T.— Ss Nochild process. 
[EBADH = =—sS«(3520.——sHandleisnotvalid, = 


iN YREFS 3523 The operation would have exceeded the 


maximum number of references allowed 
for a descriptor. 


[ENOTSAFE =——s [3524s |Functionisnotallowed. = 
ESC aW—— sk —— pice ee ——— 
[EIRNDAMAGE ~—[3526 Ss |Jourmalisdamaged. 
[EJRNINACTIVE ~— [3527s |Jourmalisimactive, = 
[EIRNRCVSPC [3528 = s‘|Journal space or system storage error. 
[EIRNRMT = ——s*(3529, Ss Journalisremote. 
[ENEWJRNRCV [3530s [New journal receiver isneeded. 
[ENEWJRN  ———s«(3531.=——Ss New journalisneeded. = 
[EJOURNALED [3532s Objectalready journaled. = 
[EIRNENTTOOLONG 3533 [Entry istoolargetosend. 
[EDATALINK —s [3534s [Object is adatalink object. 
[ENOTAVAIL ~—s 3535. IASPisnotavailable. = 


[ENOTTY = OTTY [35360 [I/O control operation is not appropriate. control [I/O control operation is not appropriate. is not appropriate. 

sues 3540 Attempt to write or truncate file past its 
=o ie file size limit. 

[ETXTBSY [35430 [Textfilebusy. file [Textfilebusy. 

SENG OTSET ~— [ASP group not set forthread. [ASP group not set forthread. not set for thread. 


—— a A system call was interrupted and may be 
restarted. 
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